@agent-native/core 0.68.3 → 0.70.0

package/dist/server/attribution.d.ts

@@ -0,0 +1,83 @@
+/**
+ * First-touch referral attribution — server side.
+ *
+ * The browser captures an anonymous visitor's *first* landing context (referral
+ * source, UTM params, referring host, landing path) and persists it across the
+ * signup boundary in a first-party cookie named `an_ft` (see
+ * `client/analytics.ts`). On signup, the auth hook reads that cookie off the
+ * request and enriches the canonical server-side `signup` event so we can
+ * measure where new users came from and how apps spread (virality).
+ *
+ * This module is intentionally pure and dependency-free so it is trivially
+ * unit-testable and can never throw into the signup path. The single hard rule:
+ * parsing untrusted cookie input must NEVER throw — every accessor is defensive.
+ */
+/**
+ * The decoded first-touch attribution object. Mirrors the compact JSON the
+ * client writes into the `an_ft` cookie / `an_attribution` localStorage key.
+ * Every field is optional — the client omits empty fields to keep the cookie
+ * small, and a malformed/absent cookie yields `null`.
+ */
+export interface FirstTouchAttribution {
+    /** Referral source bucket, e.g. "clip_share", "plan_share". */
+    ref?: string;
+    /** Referrer's stable user id (the clip/plan owner who shared the link). */
+    via?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+    /** `window.location.pathname` of the first page the visitor landed on. */
+    landing_path?: string;
+    /** Host of `document.referrer` (scrubbed; host only, never a full URL). */
+    landing_referrer?: string;
+    /** ISO timestamp of when the visitor first landed. */
+    landed_at?: string;
+}
+/** Cookie name written by the client (non-HttpOnly; non-sensitive). */
+export declare const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+/**
+ * Parse a raw `Cookie:` header into a flat name→value map. Tolerates missing
+ * input, extra whitespace, `=` inside values, and malformed pairs. Never throws.
+ */
+export declare function parseCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
+/**
+ * Decode a single cookie value into a `FirstTouchAttribution`. The value is the
+ * URL-encoded compact JSON written by the client. Returns `null` for empty,
+ * malformed, or non-object input. Only known string fields are copied through,
+ * each clamped to a sane max length as a defense against an oversized cookie.
+ */
+export declare function decodeFirstTouchValue(value: string | null | undefined): FirstTouchAttribution | null;
+/**
+ * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.
+ * Returns `null` when the cookie is absent or unparseable. Never throws.
+ */
+export declare function readFirstTouchAttribution(cookieHeader: string | null | undefined): FirstTouchAttribution | null;
+/**
+ * Derive the `referral_source` bucket from first-touch attribution per the
+ * contract:
+ *   1. explicit `ref` wins;
+ *   2. landing path under `/share/` => "clip_share";
+ *   3. landing path that looks like a public plan page
+ *      (contains `/p/`, `/plan/`, or `/share-plan/`) => "plan_share";
+ *   4. a non-empty external referring host => "external";
+ *   5. otherwise => "direct".
+ */
+export declare function deriveReferralSource(ft: FirstTouchAttribution | null): string;
+/**
+ * Compute the snake_case signup-event properties from first-touch attribution.
+ * Returns a clean object with `undefined` values omitted, ready to merge into
+ * the `signup` track call. Always sets `referral_source` (defaults to "direct").
+ *
+ * Pure and total — given any (or no) input it returns a well-formed object and
+ * never throws.
+ */
+export declare function deriveSignupAttribution(ft: FirstTouchAttribution | null): Record<string, string>;
+/**
+ * Convenience: read the cookie header and derive signup attribution in one
+ * call. Never throws; falls back to `{ referral_source: "direct" }` on any
+ * error.
+ */
+export declare function signupAttributionFromCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/server/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAe/C;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,qBAAqB,GAAG,IAAI,CA8B9B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACtC,qBAAqB,GAAG,IAAI,CAO9B;AAOD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAa7E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,qBAAqB,GAAG,IAAI,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuBxB;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}

package/dist/server/attribution.js

@@ -0,0 +1,178 @@
+/**
+ * First-touch referral attribution — server side.
+ *
+ * The browser captures an anonymous visitor's *first* landing context (referral
+ * source, UTM params, referring host, landing path) and persists it across the
+ * signup boundary in a first-party cookie named `an_ft` (see
+ * `client/analytics.ts`). On signup, the auth hook reads that cookie off the
+ * request and enriches the canonical server-side `signup` event so we can
+ * measure where new users came from and how apps spread (virality).
+ *
+ * This module is intentionally pure and dependency-free so it is trivially
+ * unit-testable and can never throw into the signup path. The single hard rule:
+ * parsing untrusted cookie input must NEVER throw — every accessor is defensive.
+ */
+/** Cookie name written by the client (non-HttpOnly; non-sensitive). */
+export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
+const STRING_FIELDS = [
+    "ref",
+    "via",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_content",
+    "utm_term",
+    "landing_path",
+    "landing_referrer",
+    "landed_at",
+];
+/**
+ * Parse a raw `Cookie:` header into a flat name→value map. Tolerates missing
+ * input, extra whitespace, `=` inside values, and malformed pairs. Never throws.
+ */
+export function parseCookieHeader(cookieHeader) {
+    const out = {};
+    if (!cookieHeader || typeof cookieHeader !== "string")
+        return out;
+    for (const part of cookieHeader.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name)
+            continue;
+        const rawValue = part.slice(eq + 1).trim();
+        // First write wins so a duplicate cookie name can't clobber the first.
+        if (name in out)
+            continue;
+        out[name] = rawValue;
+    }
+    return out;
+}
+/**
+ * Decode a single cookie value into a `FirstTouchAttribution`. The value is the
+ * URL-encoded compact JSON written by the client. Returns `null` for empty,
+ * malformed, or non-object input. Only known string fields are copied through,
+ * each clamped to a sane max length as a defense against an oversized cookie.
+ */
+export function decodeFirstTouchValue(value) {
+    if (!value || typeof value !== "string")
+        return null;
+    let decoded = value;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        // Not valid percent-encoding — fall back to the raw value and let the JSON
+        // parse below decide whether it's usable.
+        decoded = value;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const source = parsed;
+    const result = {};
+    let any = false;
+    for (const field of STRING_FIELDS) {
+        const raw = source[field];
+        if (typeof raw === "string" && raw.length > 0) {
+            result[field] = raw.slice(0, 120);
+            any = true;
+        }
+    }
+    return any ? result : null;
+}
+/**
+ * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.
+ * Returns `null` when the cookie is absent or unparseable. Never throws.
+ */
+export function readFirstTouchAttribution(cookieHeader) {
+    try {
+        const cookies = parseCookieHeader(cookieHeader);
+        return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);
+    }
+    catch {
+        return null;
+    }
+}
+function isExternalReferrerHost(host) {
+    const trimmed = host?.trim();
+    return !!trimmed && trimmed.length > 0;
+}
+/**
+ * Derive the `referral_source` bucket from first-touch attribution per the
+ * contract:
+ *   1. explicit `ref` wins;
+ *   2. landing path under `/share/` => "clip_share";
+ *   3. landing path that looks like a public plan page
+ *      (contains `/p/`, `/plan/`, or `/share-plan/`) => "plan_share";
+ *   4. a non-empty external referring host => "external";
+ *   5. otherwise => "direct".
+ */
+export function deriveReferralSource(ft) {
+    if (ft?.ref && ft.ref.trim())
+        return ft.ref.trim();
+    const path = ft?.landing_path ?? "";
+    if (path.startsWith("/share/"))
+        return "clip_share";
+    if (path.includes("/p/") ||
+        path.includes("/plan/") ||
+        path.includes("/share-plan/")) {
+        return "plan_share";
+    }
+    if (isExternalReferrerHost(ft?.landing_referrer))
+        return "external";
+    return "direct";
+}
+/**
+ * Compute the snake_case signup-event properties from first-touch attribution.
+ * Returns a clean object with `undefined` values omitted, ready to merge into
+ * the `signup` track call. Always sets `referral_source` (defaults to "direct").
+ *
+ * Pure and total — given any (or no) input it returns a well-formed object and
+ * never throws.
+ */
+export function deriveSignupAttribution(ft) {
+    const out = {
+        referral_source: deriveReferralSource(ft),
+    };
+    if (!ft)
+        return out;
+    const setIf = (key, value) => {
+        const trimmed = value?.trim();
+        if (trimmed)
+            out[key] = trimmed;
+    };
+    setIf("referrer_user", ft.via);
+    setIf("referral_medium", ft.utm_medium);
+    setIf("referral_campaign", ft.utm_campaign);
+    setIf("utm_source", ft.utm_source);
+    setIf("utm_medium", ft.utm_medium);
+    setIf("utm_campaign", ft.utm_campaign);
+    setIf("utm_content", ft.utm_content);
+    setIf("utm_term", ft.utm_term);
+    setIf("first_touch_path", ft.landing_path);
+    setIf("landing_referrer", ft.landing_referrer);
+    return out;
+}
+/**
+ * Convenience: read the cookie header and derive signup attribution in one
+ * call. Never throws; falls back to `{ referral_source: "direct" }` on any
+ * error.
+ */
+export function signupAttributionFromCookieHeader(cookieHeader) {
+    try {
+        return deriveSignupAttribution(readFirstTouchAttribution(cookieHeader));
+    }
+    catch {
+        return { referral_source: "direct" };
+    }
+}
+//# sourceMappingURL=attribution.js.map

package/dist/server/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/server/attribution.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * First-touch referral attribution — server side.\n *\n * The browser captures an anonymous visitor's *first* landing context (referral\n * source, UTM params, referring host, landing path) and persists it across the\n * signup boundary in a first-party cookie named `an_ft` (see\n * `client/analytics.ts`). On signup, the auth hook reads that cookie off the\n * request and enriches the canonical server-side `signup` event so we can\n * measure where new users came from and how apps spread (virality).\n *\n * This module is intentionally pure and dependency-free so it is trivially\n * unit-testable and can never throw into the signup path. The single hard rule:\n * parsing untrusted cookie input must NEVER throw — every accessor is defensive.\n */\n\n/**\n * The decoded first-touch attribution object. Mirrors the compact JSON the\n * client writes into the `an_ft` cookie / `an_attribution` localStorage key.\n * Every field is optional — the client omits empty fields to keep the cookie\n * small, and a malformed/absent cookie yields `null`.\n */\nexport interface FirstTouchAttribution {\n  /** Referral source bucket, e.g. \"clip_share\", \"plan_share\". */\n  ref?: string;\n  /** Referrer's stable user id (the clip/plan owner who shared the link). */\n  via?: string;\n  utm_source?: string;\n  utm_medium?: string;\n  utm_campaign?: string;\n  utm_content?: string;\n  utm_term?: string;\n  /** `window.location.pathname` of the first page the visitor landed on. */\n  landing_path?: string;\n  /** Host of `document.referrer` (scrubbed; host only, never a full URL). */\n  landing_referrer?: string;\n  /** ISO timestamp of when the visitor first landed. */\n  landed_at?: string;\n}\n\n/** Cookie name written by the client (non-HttpOnly; non-sensitive). */\nexport const FIRST_TOUCH_COOKIE_NAME = \"an_ft\";\n\nconst STRING_FIELDS: Array<keyof FirstTouchAttribution> = [\n  \"ref\",\n  \"via\",\n  \"utm_source\",\n  \"utm_medium\",\n  \"utm_campaign\",\n  \"utm_content\",\n  \"utm_term\",\n  \"landing_path\",\n  \"landing_referrer\",\n  \"landed_at\",\n];\n\n/**\n * Parse a raw `Cookie:` header into a flat name→value map. Tolerates missing\n * input, extra whitespace, `=` inside values, and malformed pairs. Never throws.\n */\nexport function parseCookieHeader(\n  cookieHeader: string | null | undefined,\n): Record<string, string> {\n  const out: Record<string, string> = {};\n  if (!cookieHeader || typeof cookieHeader !== \"string\") return out;\n  for (const part of cookieHeader.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq === -1) continue;\n    const name = part.slice(0, eq).trim();\n    if (!name) continue;\n    const rawValue = part.slice(eq + 1).trim();\n    // First write wins so a duplicate cookie name can't clobber the first.\n    if (name in out) continue;\n    out[name] = rawValue;\n  }\n  return out;\n}\n\n/**\n * Decode a single cookie value into a `FirstTouchAttribution`. The value is the\n * URL-encoded compact JSON written by the client. Returns `null` for empty,\n * malformed, or non-object input. Only known string fields are copied through,\n * each clamped to a sane max length as a defense against an oversized cookie.\n */\nexport function decodeFirstTouchValue(\n  value: string | null | undefined,\n): FirstTouchAttribution | null {\n  if (!value || typeof value !== \"string\") return null;\n  let decoded = value;\n  try {\n    decoded = decodeURIComponent(value);\n  } catch {\n    // Not valid percent-encoding — fall back to the raw value and let the JSON\n    // parse below decide whether it's usable.\n    decoded = value;\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(decoded);\n  } catch {\n    return null;\n  }\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n    return null;\n  }\n  const source = parsed as Record<string, unknown>;\n  const result: FirstTouchAttribution = {};\n  let any = false;\n  for (const field of STRING_FIELDS) {\n    const raw = source[field];\n    if (typeof raw === \"string\" && raw.length > 0) {\n      result[field] = raw.slice(0, 120);\n      any = true;\n    }\n  }\n  return any ? result : null;\n}\n\n/**\n * Read the `an_ft` first-touch attribution out of a raw `Cookie:` header.\n * Returns `null` when the cookie is absent or unparseable. Never throws.\n */\nexport function readFirstTouchAttribution(\n  cookieHeader: string | null | undefined,\n): FirstTouchAttribution | null {\n  try {\n    const cookies = parseCookieHeader(cookieHeader);\n    return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);\n  } catch {\n    return null;\n  }\n}\n\nfunction isExternalReferrerHost(host: string | undefined): boolean {\n  const trimmed = host?.trim();\n  return !!trimmed && trimmed.length > 0;\n}\n\n/**\n * Derive the `referral_source` bucket from first-touch attribution per the\n * contract:\n *   1. explicit `ref` wins;\n *   2. landing path under `/share/` => \"clip_share\";\n *   3. landing path that looks like a public plan page\n *      (contains `/p/`, `/plan/`, or `/share-plan/`) => \"plan_share\";\n *   4. a non-empty external referring host => \"external\";\n *   5. otherwise => \"direct\".\n */\nexport function deriveReferralSource(ft: FirstTouchAttribution | null): string {\n  if (ft?.ref && ft.ref.trim()) return ft.ref.trim();\n  const path = ft?.landing_path ?? \"\";\n  if (path.startsWith(\"/share/\")) return \"clip_share\";\n  if (\n    path.includes(\"/p/\") ||\n    path.includes(\"/plan/\") ||\n    path.includes(\"/share-plan/\")\n  ) {\n    return \"plan_share\";\n  }\n  if (isExternalReferrerHost(ft?.landing_referrer)) return \"external\";\n  return \"direct\";\n}\n\n/**\n * Compute the snake_case signup-event properties from first-touch attribution.\n * Returns a clean object with `undefined` values omitted, ready to merge into\n * the `signup` track call. Always sets `referral_source` (defaults to \"direct\").\n *\n * Pure and total — given any (or no) input it returns a well-formed object and\n * never throws.\n */\nexport function deriveSignupAttribution(\n  ft: FirstTouchAttribution | null,\n): Record<string, string> {\n  const out: Record<string, string> = {\n    referral_source: deriveReferralSource(ft),\n  };\n  if (!ft) return out;\n\n  const setIf = (key: string, value: string | undefined) => {\n    const trimmed = value?.trim();\n    if (trimmed) out[key] = trimmed;\n  };\n\n  setIf(\"referrer_user\", ft.via);\n  setIf(\"referral_medium\", ft.utm_medium);\n  setIf(\"referral_campaign\", ft.utm_campaign);\n  setIf(\"utm_source\", ft.utm_source);\n  setIf(\"utm_medium\", ft.utm_medium);\n  setIf(\"utm_campaign\", ft.utm_campaign);\n  setIf(\"utm_content\", ft.utm_content);\n  setIf(\"utm_term\", ft.utm_term);\n  setIf(\"first_touch_path\", ft.landing_path);\n  setIf(\"landing_referrer\", ft.landing_referrer);\n\n  return out;\n}\n\n/**\n * Convenience: read the cookie header and derive signup attribution in one\n * call. Never throws; falls back to `{ referral_source: \"direct\" }` on any\n * error.\n */\nexport function signupAttributionFromCookieHeader(\n  cookieHeader: string | null | undefined,\n): Record<string, string> {\n  try {\n    return deriveSignupAttribution(readFirstTouchAttribution(cookieHeader));\n  } catch {\n    return { referral_source: \"direct\" };\n  }\n}\n"]}

package/dist/server/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"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"}

package/dist/server/auth.js

@@ -1312,6 +1312,13 @@ function createAuthGuardFn() {
             return;
         if (p === "/_agent-native/speculation-rules.json")
             return;
+        // Liveness probe: always public so uptime monitors and the keep-warm cron
+        // can reach the DB-warmup route without a session. It exposes no per-user
+        // data (just ok/db/ms) and runs a trivial `SELECT 1`. Without this bypass
+        // the gate below 401s anonymous /_agent-native/* requests before any DB
+        // query, so the database would never get warmed.
+        if (p === "/_agent-native/health")
+            return;
         if (isPublicPath(normalizedUrl, publicPaths))
             return;
         if (shouldBypassAuthForBuilderConnect(event, p))