@agent-native/core 0.214.0 → 0.216.0

package/dist/server/attribution.d.ts

@@ -13,6 +13,10 @@
  * acquisition; last touch answers "what brought them to sign up?" and credits
  * the post, video, or person that converted them.
  *
+ * First touch also has a durable copy, `an_fts`, that our server sets for a
+ * year (see `first-touch-route.ts`). Signup reads both first-touch cookies and
+ * keeps the one `preferFirstTouch` picks.
+ *
  * 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.
@@ -80,11 +84,21 @@ export declare const LAST_TOUCH_COOKIE_NAME = "an_lt";
 export declare function parseCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
 export declare function decodeFirstTouchValue(value: string | null | undefined): FirstTouchAttribution | null;
 export declare function decodeLastTouchValue(value: string | null | undefined): LastTouchAttribution | null;
+/**
+ * Decode the year-long `an_fts` cookie. A value from another format version
+ * is unreadable here, so it holds no touch.
+ */
+export declare function decodeFirstTouchServerValue(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;
+/**
+ * The `an_fts` cookie value for a first touch, dropping the lowest-priority
+ * fields until `name=value` fits its budget.
+ */
+export declare function encodeFirstTouchServerCookieValue(touch: FirstTouchAttribution): string;
 /**
  * Read the `an_lt` last-touch attribution out of a raw `Cookie:` header.
  * Returns `null` when the cookie is absent or unparseable. Never throws.

package/dist/server/attribution.js

@@ -1,6 +1,7 @@
 import { ANALYTICS_ANONYMOUS_ID_COOKIE_NAME, ANALYTICS_ANONYMOUS_ID_MAX_LENGTH, normalizeAnalyticsAnonymousId, } from "../shared/analytics-anonymous-id.js";
 import { ANALYTICS_SESSION_ID_COOKIE_NAME, normalizeAnalyticsSessionId, } from "../shared/analytics-session-id.js";
 import { isSourceReferrerHost, shareLandingSource, } from "../shared/attribution-source.js";
+import { FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES, FIRST_TOUCH_SERVER_COOKIE_NAME, FIRST_TOUCH_SERVER_COOKIE_VERSION, preferFirstTouch, } from "../shared/first-touch-persistence.js";
 export const SIGNUP_ATTRIBUTION_HEADER_NAME = "x-agent-native-signup-attribution";
 const SIGNUP_ATTRIBUTION_HEADER_MAX_LENGTH = 4096;
 export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
@@ -70,7 +71,14 @@ export function decodeFirstTouchValue(value) {
 export function decodeLastTouchValue(value) {
     return decodeAttributionCookieValue(value, LAST_TOUCH_STRING_FIELDS);
 }
-function decodeAttributionCookieValue(value, fields) {
+/**
+ * Decode the year-long `an_fts` cookie. A value from another format version
+ * is unreadable here, so it holds no touch.
+ */
+export function decodeFirstTouchServerValue(value) {
+    return decodeAttributionCookieValue(value, STRING_FIELDS, FIRST_TOUCH_SERVER_COOKIE_VERSION);
+}
+function decodeAttributionCookieValue(value, fields, version) {
     if (!value || typeof value !== "string")
         return null;
     let decoded = value;
@@ -91,6 +99,8 @@ function decodeAttributionCookieValue(value, fields) {
         return null;
     }
     const source = parsed;
+    if (version !== undefined && source.v !== version)
+        return null;
     const result = {};
     let any = false;
     for (const field of fields) {
@@ -109,12 +119,62 @@ function decodeAttributionCookieValue(value, fields) {
 export function readFirstTouchAttribution(cookieHeader) {
     try {
         const cookies = parseCookieHeader(cookieHeader);
-        return decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]);
+        return preferFirstTouch(decodeFirstTouchServerValue(cookies[FIRST_TOUCH_SERVER_COOKIE_NAME]), decodeFirstTouchValue(cookies[FIRST_TOUCH_COOKIE_NAME]));
     }
     catch {
         return null;
     }
 }
+// `landed_at` sets the cookie's expiry and identifies the visit, so it is
+// never the field dropped to fit.
+const FIRST_TOUCH_SERVER_FIELD_PRIORITY = [
+    "landed_at",
+    "gclid",
+    "msclkid",
+    "vector_source",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "ref",
+    "via",
+    "utm_content",
+    "utm_term",
+    "landing_path",
+    "landing_referrer",
+    "site_referrer",
+    "site_landing_path",
+];
+/**
+ * The `an_fts` cookie value for a first touch, dropping the lowest-priority
+ * fields until `name=value` fits its budget.
+ */
+export function encodeFirstTouchServerCookieValue(touch) {
+    const compact = {
+        v: FIRST_TOUCH_SERVER_COOKIE_VERSION,
+    };
+    let truncated = touch.capture_truncated === "1";
+    const encode = (value) => encodeURIComponent(JSON.stringify(value));
+    const fits = (value) => FIRST_TOUCH_SERVER_COOKIE_NAME.length + 1 + encode(value).length <=
+        FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES;
+    // Room for the marker, so adding it later can't push the value over.
+    const withMarker = (value) => ({
+        ...value,
+        capture_truncated: "1",
+    });
+    for (const field of FIRST_TOUCH_SERVER_FIELD_PRIORITY) {
+        const value = touch[field];
+        if (!value)
+            continue;
+        const candidate = { ...compact, [field]: value };
+        if (fits(withMarker(candidate))) {
+            compact[field] = value;
+        }
+        else {
+            truncated = true;
+        }
+    }
+    return encode(truncated ? withMarker(compact) : compact);
+}
 /**
  * Read the `an_lt` last-touch attribution out of a raw `Cookie:` header.
  * Returns `null` when the cookie is absent or unparseable. Never throws.

package/dist/server/auth.js

@@ -5,14 +5,18 @@ import { acceptPendingInvitationsForEmail } from "../org/accept-pending.js";
 import { newOrgSelection, ORG_SELECTION_COOKIE, } from "../org/request-org-cache.js";
 import { isWorkspaceAppAccessUnavailable, workspaceAppAccessUnavailableBody, } from "../org/workspace-app-access-outcome.js";
 import { checkWorkspaceAppAccessForRequest } from "../org/workspace-app-access-request.js";
+import { CONSENT_PATH, CONSENT_REGION_PATH } from "../shared/consent.js";
 import { EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TARGET_HEADER, isMcpDirectoryWidgetCapabilityScope, } from "../shared/embed-auth.js";
 import { FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_MAX_AGE, } from "../shared/first-run-onboarding.js";
+import { FIRST_TOUCH_SERVER_PATH } from "../shared/first-touch-persistence.js";
 import { isGoogleProfileImageUrl } from "../shared/google-profile-image.js";
 import { EMBED_TRANSPLANT_HEADER, isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
+import { createConsentHandler, createConsentRegionHandler, } from "./consent-route.js";
 import { readDevActionDiscoveryFile } from "./dev-action-discovery.js";
 import { devLoopbackAuthHint } from "./dev-origin-hint.js";
 import { EMAIL_AUTH_LINK_LANDING_PATH, emailAuthLinkFields, emailAuthLinkLandingPage, emailAuthVerificationPath, emailAuthVerificationUrl, } from "./email-auth-links.js";
 import { isEmbedCapabilityScope, revokeEmbedSessionsForOwners, requestHasEmbedAuthMarker, resolveEmbedSessionCookieOwners, resolveEmbedSessionFromRequest, verifyEmbedSessionToken, } from "./embed-session.js";
+import { createFirstTouchHandler } from "./first-touch-route.js";
 import { getPublicFrameworkPathname } from "./framework-request-context.js";
 import { FRAMEWORK_INTERNAL_ROUTE_PREFIX, canonicalFrameworkPathname, getFrameworkRoutePrefix, publicFrameworkPath, } from "./framework-route-prefix.js";
 import { isHttpsRequest } from "./https-request.js";
@@ -5547,6 +5551,9 @@ export async function autoMountAuth(app, options = {}) {
     const workspaceAppAudience = resolveWorkspaceAppAudience(options);
     const workspaceAppRouteAccess = resolveWorkspaceAppRouteAccess(options);
     mountAuthCorsMiddleware(app);
+    app.use(FIRST_TOUCH_SERVER_PATH, createFirstTouchHandler());
+    app.use(CONSENT_REGION_PATH, createConsentRegionHandler());
+    app.use(CONSENT_PATH, createConsentHandler());
     if (options.getSession) {
         customGetSession = options.getSession;
         trustCustomEmailVerification =

package/dist/server/consent-route.d.ts

@@ -0,0 +1,41 @@
+import type { H3Event } from "h3";
+import { type ConsentCategory } from "../shared/consent.js";
+/**
+ * The visitor's country from the host's geo header, if it sent one. The
+ * headers a CDN always overwrites come first, so a visitor's own `x-country`
+ * can't outrank them.
+ */
+export declare function requestCountry(event: H3Event): string | undefined;
+/**
+ * A stored choice applies everywhere; without one, the country decides
+ * whether storing `category` cookies requires an opt-in.
+ */
+export declare function requestAllowsConsentCategory(event: H3Event, category: ConsentCategory): boolean;
+/**
+ * `GET /_agent-native/auth/consent-region`: `consent` when the visitor's
+ * country gets the banner, `none` when it doesn't, `unknown` when the host
+ * sent no country. The SSR shell is cached for everyone, so the browser asks
+ * here instead of reading it from the page.
+ */
+export declare function createConsentRegionHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, {
+    error: string;
+    region?: undefined;
+} | {
+    error?: undefined;
+    region: string;
+}>;
+/**
+ * `POST /_agent-native/auth/consent` with `{ choice: "1.p1.t0" }`: write the
+ * visitor's choice from the server. Safari keeps a cookie page JavaScript
+ * wrote for seven days at most, and builder.io asks again only after a year.
+ * Uses the same domain as the browser's copy, so it replaces that copy.
+ */
+export declare function createConsentHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    error: string;
+    stored?: undefined;
+    choice?: undefined;
+} | {
+    error?: undefined;
+    stored: boolean;
+    choice: any;
+}>>;

package/dist/server/consent-route.js

@@ -0,0 +1,102 @@
+import { appendResponseHeader, defineEventHandler, getHeader, getMethod, setResponseHeader, setResponseStatus, } from "h3";
+import { CONSENT_COOKIE_LIFETIME_SECONDS, CONSENT_COOKIE_NAME, consentCookieDomain, isConsentRegionCountry, parseConsent, serializeConsent, } from "../shared/consent.js";
+import { parseCookieHeader } from "./attribution.js";
+import { readBodyWithSizeLimit } from "./h3-helpers.js";
+import { getForwardedRequestOrigin, getForwardedRequestURL, isSameOriginPost, } from "./request-origin.js";
+const MAX_CONSENT_BODY_BYTES = 256;
+/**
+ * The visitor's country from the host's geo header, if it sent one. The
+ * headers a CDN always overwrites come first, so a visitor's own `x-country`
+ * can't outrank them.
+ */
+export function requestCountry(event) {
+    return (netlifyGeoCountry(event) ??
+        getHeader(event, "cf-ipcountry") ??
+        getHeader(event, "x-vercel-ip-country") ??
+        getHeader(event, "x-country"));
+}
+function netlifyGeoCountry(event) {
+    const geo = getHeader(event, "x-nf-geo");
+    if (!geo)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(geo, "base64").toString("utf8"));
+        const code = parsed?.country?.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        // coercion-ok: an unreadable geo header is an unknown country; the next
+        // header, or the browser's time zone, decides.
+        return undefined;
+    }
+}
+/**
+ * A stored choice applies everywhere; without one, the country decides
+ * whether storing `category` cookies requires an opt-in.
+ */
+export function requestAllowsConsentCategory(event, category) {
+    const consent = parseConsent(parseCookieHeader(getHeader(event, "cookie"))[CONSENT_COOKIE_NAME]);
+    if (consent)
+        return consent[category];
+    return !isConsentRegionCountry(requestCountry(event));
+}
+/**
+ * `GET /_agent-native/auth/consent-region`: `consent` when the visitor's
+ * country gets the banner, `none` when it doesn't, `unknown` when the host
+ * sent no country. The SSR shell is cached for everyone, so the browser asks
+ * here instead of reading it from the page.
+ */
+export function createConsentRegionHandler() {
+    return defineEventHandler((event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const country = requestCountry(event);
+        if (!country)
+            return { region: "unknown" };
+        return { region: isConsentRegionCountry(country) ? "consent" : "none" };
+    });
+}
+/**
+ * `POST /_agent-native/auth/consent` with `{ choice: "1.p1.t0" }`: write the
+ * visitor's choice from the server. Safari keeps a cookie page JavaScript
+ * wrote for seven days at most, and builder.io asks again only after a year.
+ * Uses the same domain as the browser's copy, so it replaces that copy.
+ */
+export function createConsentHandler() {
+    return defineEventHandler(async (event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        if (!isSameOriginPost(event)) {
+            setResponseStatus(event, 403);
+            return { error: "Cross-origin request" };
+        }
+        let choice;
+        try {
+            const body = await readBodyWithSizeLimit(event, MAX_CONSENT_BODY_BYTES);
+            choice = parseConsent(body?.choice);
+        }
+        catch (error) {
+            if (error.statusCode === 413) {
+                return { error: "Body too large" };
+            }
+            setResponseStatus(event, 400);
+            return { error: "Invalid JSON" };
+        }
+        if (!choice) {
+            setResponseStatus(event, 400);
+            return { error: "Missing choice" };
+        }
+        const domain = consentCookieDomain(getForwardedRequestURL(event).hostname);
+        const secure = getForwardedRequestOrigin(event).startsWith("https:");
+        appendResponseHeader(event, "set-cookie", `${CONSENT_COOKIE_NAME}=${serializeConsent(choice)}; ` +
+            `Max-Age=${CONSENT_COOKIE_LIFETIME_SECONDS}; Path=/; SameSite=Lax` +
+            `${domain ? `; Domain=${domain}` : ""}${secure ? "; Secure" : ""}`);
+        return { stored: true, choice };
+    });
+}

package/dist/server/first-touch-route.d.ts

@@ -0,0 +1,39 @@
+import { type FirstTouchAttribution } from "./attribution.js";
+export type FirstTouchSyncResult = {
+    stored: true;
+    firstTouch: FirstTouchAttribution;
+} | {
+    stored: false;
+    reason: "consent_required" | "expired";
+};
+/**
+ * `POST /_agent-native/auth/attribution` with `{ firstTouch }`: keep the
+ * browser's first touch in the year-long `an_fts` cookie. Anyone may call it,
+ * signed in or not, but only from this origin. The value already in the
+ * cookie wins unless `preferFirstTouch` picks the new one, so a slow request
+ * from another tab can't replace a better first touch it never saw. Where the
+ * banner applies and the visitor hasn't accepted targeting cookies, it stores
+ * nothing and clears every attribution cookie. Elsewhere it also writes the
+ * browser's `an_ft` and `an_lt` again, so Safari keeps them their 30 days.
+ */
+export declare function createFirstTouchHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    reason?: undefined;
+    error: string;
+    stored?: undefined;
+    firstTouch?: undefined;
+} | {
+    error?: undefined;
+    stored: false;
+    reason: "consent_required";
+    firstTouch?: undefined;
+} | {
+    error?: undefined;
+    stored: false;
+    reason: "expired";
+    firstTouch?: undefined;
+} | {
+    reason?: undefined;
+    error?: undefined;
+    stored: true;
+    firstTouch: FirstTouchAttribution;
+}>>;

package/dist/server/first-touch-route.js

@@ -0,0 +1,115 @@
+import { appendResponseHeader, defineEventHandler, getHeader, getMethod, setResponseHeader, setResponseStatus, } from "h3";
+import { FIRST_TOUCH_SERVER_COOKIE_NAME, firstTouchServerExpiry, preferFirstTouch, } from "../shared/first-touch-persistence.js";
+import { FIRST_TOUCH_COOKIE_NAME, LAST_TOUCH_COOKIE_NAME, decodeFirstTouchServerValue, decodeFirstTouchValue, decodeLastTouchValue, encodeFirstTouchServerCookieValue, parseCookieHeader, } from "./attribution.js";
+import { requestAllowsConsentCategory } from "./consent-route.js";
+import { readBodyWithSizeLimit } from "./h3-helpers.js";
+import { getForwardedRequestOrigin, isSameOriginPost, } from "./request-origin.js";
+const MAX_BODY_BYTES = 8 * 1024;
+/** How long the browser's own `an_ft` and `an_lt` copies last. */
+const BROWSER_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+const BROWSER_COOKIES = [
+    { name: FIRST_TOUCH_COOKIE_NAME, decode: decodeFirstTouchValue },
+    { name: LAST_TOUCH_COOKIE_NAME, decode: decodeLastTouchValue },
+];
+// What `encodeURIComponent` emits, so a value echoed into Set-Cookie can't
+// carry an attribute or a header break.
+const ENCODED_COOKIE_VALUE = /^[A-Za-z0-9\-_.!~*'()%]{1,1500}$/;
+function cookieAttributes(event) {
+    const secure = getForwardedRequestOrigin(event).startsWith("https:");
+    return `Path=/; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+function clearAttributionCookies(event) {
+    for (const name of [
+        FIRST_TOUCH_SERVER_COOKIE_NAME,
+        FIRST_TOUCH_COOKIE_NAME,
+        LAST_TOUCH_COOKIE_NAME,
+    ]) {
+        appendResponseHeader(event, "set-cookie", `${name}=; Max-Age=0; ${cookieAttributes(event)}`);
+    }
+}
+/**
+ * Safari keeps a cookie page JavaScript wrote for seven days at most, so write
+ * the browser's own `an_ft` and `an_lt` again from here, for their full 30
+ * days. Only values that decode as touches are echoed back.
+ */
+function resetBrowserCookies(event) {
+    const cookies = parseCookieHeader(getHeader(event, "cookie"));
+    for (const { name, decode } of BROWSER_COOKIES) {
+        const value = cookies[name];
+        if (!value || !ENCODED_COOKIE_VALUE.test(value) || !decode(value)) {
+            continue;
+        }
+        appendResponseHeader(event, "set-cookie", `${name}=${value}; Max-Age=${BROWSER_COOKIE_MAX_AGE_SECONDS}; ${cookieAttributes(event)}`);
+    }
+}
+function readCandidate(body) {
+    const firstTouch = body?.firstTouch;
+    if (!firstTouch || typeof firstTouch !== "object")
+        return null;
+    return decodeFirstTouchValue(encodeURIComponent(JSON.stringify(firstTouch)));
+}
+/** A touch more than a year old can't be kept, or win against one that can. */
+function unexpired(touch) {
+    return touch && firstTouchServerExpiry(touch) ? touch : null;
+}
+/**
+ * `POST /_agent-native/auth/attribution` with `{ firstTouch }`: keep the
+ * browser's first touch in the year-long `an_fts` cookie. Anyone may call it,
+ * signed in or not, but only from this origin. The value already in the
+ * cookie wins unless `preferFirstTouch` picks the new one, so a slow request
+ * from another tab can't replace a better first touch it never saw. Where the
+ * banner applies and the visitor hasn't accepted targeting cookies, it stores
+ * nothing and clears every attribution cookie. Elsewhere it also writes the
+ * browser's `an_ft` and `an_lt` again, so Safari keeps them their 30 days.
+ */
+export function createFirstTouchHandler() {
+    return defineEventHandler(async (event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        if (!isSameOriginPost(event)) {
+            setResponseStatus(event, 403);
+            return { error: "Cross-origin request" };
+        }
+        let body;
+        try {
+            body = await readBodyWithSizeLimit(event, MAX_BODY_BYTES);
+        }
+        catch (error) {
+            if (error.statusCode === 413) {
+                return { error: "Body too large" };
+            }
+            setResponseStatus(event, 400);
+            return { error: "Invalid JSON" };
+        }
+        if (!requestAllowsConsentCategory(event, "targeting")) {
+            clearAttributionCookies(event);
+            return {
+                stored: false,
+                reason: "consent_required",
+            };
+        }
+        const candidate = readCandidate(body);
+        if (!candidate) {
+            setResponseStatus(event, 400);
+            return { error: "Missing firstTouch" };
+        }
+        resetBrowserCookies(event);
+        const existing = decodeFirstTouchServerValue(parseCookieHeader(getHeader(event, "cookie"))[FIRST_TOUCH_SERVER_COOKIE_NAME]);
+        const firstTouch = preferFirstTouch(unexpired(existing), unexpired(candidate));
+        const expires = firstTouch && firstTouchServerExpiry(firstTouch);
+        if (!firstTouch || !expires) {
+            return {
+                stored: false,
+                reason: "expired",
+            };
+        }
+        if (firstTouch !== existing) {
+            appendResponseHeader(event, "set-cookie", `${FIRST_TOUCH_SERVER_COOKIE_NAME}=${encodeFirstTouchServerCookieValue(firstTouch)}; ` +
+                `Expires=${expires.toUTCString()}; ${cookieAttributes(event)}`);
+        }
+        return { stored: true, firstTouch };
+    });
+}

package/dist/server/index.d.ts

@@ -127,3 +127,4 @@ export { AGENT_READABLE_RESOURCE_PAYLOAD_TYPE, AGENT_READABLE_RESOURCE_SCRIPT_TY
 export { registerObservabilityProvider, type ObservabilityMeterProvider, type ObservabilityProvider, type ObservabilityTracerProvider, } from "../observability/otel-provider.js";
 export type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 export declare function defineNitroPlugin(def: NitroPluginDef): NitroPluginDef;
+export { appStateListKeysByKeySuffixPrefix } from "./application-state-maintenance.js";

package/dist/server/index.js

@@ -122,3 +122,4 @@ export { registerObservabilityProvider, } from "../observability/otel-provider.j
 export function defineNitroPlugin(def) {
     return def;
 }
+export { appStateListKeysByKeySuffixPrefix } from "./application-state-maintenance.js";

package/dist/server/queued-submission-inbox-drain.d.ts

@@ -0,0 +1,9 @@
+export declare function scheduleQueuedSubmissionInboxDrain(input: {
+    threadId: string;
+    turnContinues: boolean;
+    waitUntil?: (promise: Promise<unknown>) => void;
+    drain: (input: {
+        threadId: string;
+    }) => Promise<unknown>;
+    onError: (error: unknown) => void;
+}): void;

package/dist/server/queued-submission-inbox-drain.js

@@ -0,0 +1,12 @@
+import { runWithoutExecutionFence } from "../agent/execution-fence.js";
+export function scheduleQueuedSubmissionInboxDrain(input) {
+    if (input.turnContinues)
+        return;
+    const drain = Promise.resolve()
+        .then(() => runWithoutExecutionFence(() => input.drain({ threadId: input.threadId })))
+        .catch(input.onError);
+    if (input.waitUntil)
+        input.waitUntil(drain);
+    else
+        void drain;
+}

package/dist/server/request-origin.d.ts

@@ -4,4 +4,10 @@ export declare function getForwardedRequestOrigin(event: H3Event): string;
 export declare function getForwardedRequestURL(event: H3Event): URL;
 export declare function getForwardedRequestHostname(event: H3Event): string;
 export declare function getForwardedRequestHostnameFromHeaders(headers: Headers | IncomingHttpHeaders, remoteAddress?: string): string;
+/**
+ * Stricter than `isSameOriginRequest`, for a POST that writes cookies: a
+ * request with neither header, a navigation, or a desktop shell's origin
+ * can't prove it came from this site's pages.
+ */
+export declare function isSameOriginPost(event: H3Event): boolean;
 export declare function isSameOriginRequest(event: H3Event): boolean;

package/dist/server/request-origin.js

@@ -95,6 +95,18 @@ export function getForwardedRequestHostnameFromHeaders(headers, remoteAddress) {
 function isLoopbackHost(host) {
     return host.startsWith("localhost:") || host.startsWith("127.0.0.1:");
 }
+/**
+ * Stricter than `isSameOriginRequest`, for a POST that writes cookies: a
+ * request with neither header, a navigation, or a desktop shell's origin
+ * can't prove it came from this site's pages.
+ */
+export function isSameOriginPost(event) {
+    const fetchSite = getRequestHeader(event, "sec-fetch-site");
+    if (fetchSite)
+        return fetchSite === "same-origin";
+    const origin = getRequestHeader(event, "origin");
+    return !!origin && origin === getForwardedRequestOrigin(event);
+}
 export function isSameOriginRequest(event) {
     const fetchSite = getRequestHeader(event, "sec-fetch-site");
     if (fetchSite)

package/dist/settings/org-settings.d.ts

@@ -1,5 +1,6 @@
-import { type StoreWriteOptions, type StoreReadOptions } from "./store.js";
+import { type SettingEntry, type StoreWriteOptions, type StoreReadOptions } from "./store.js";
 export declare function getOrgSetting(orgId: string, key: string, options?: StoreReadOptions): Promise<Record<string, unknown> | null>;
+export declare function getOrgSettingEntry(orgId: string, key: string, options?: StoreReadOptions): Promise<SettingEntry>;
 export declare function putOrgSetting(orgId: string, key: string, value: Record<string, unknown>, options?: StoreWriteOptions): Promise<void>;
 export declare function mutateOrgSetting(orgId: string, key: string, updater: (current: Record<string, unknown> | null) => Record<string, unknown> | Promise<Record<string, unknown>>, options?: StoreWriteOptions): Promise<Record<string, unknown>>;
 export declare function deleteOrgSetting(orgId: string, key: string, options?: StoreWriteOptions): Promise<boolean>;

package/dist/settings/org-settings.js

@@ -1,4 +1,4 @@
-import { getSetting, mutateSetting, putSetting, deleteSetting, deleteSettingsByPrefix, listSettingsByPrefix, } from "./store.js";
+import { getSetting, getSettingEntry, mutateSetting, putSetting, deleteSetting, deleteSettingsByPrefix, listSettingsByPrefix, } from "./store.js";
 function orgKey(orgId, key) {
     return `o:${orgId}:${key}`;
 }
@@ -6,6 +6,9 @@ const ORG_PREFIX_RE = /^o:([^:]+):(.+)$/;
 export async function getOrgSetting(orgId, key, options) {
     return getSetting(orgKey(orgId, key), options);
 }
+export async function getOrgSettingEntry(orgId, key, options) {
+    return getSettingEntry(orgKey(orgId, key), options);
+}
 export async function putOrgSetting(orgId, key, value, options) {
     return putSetting(orgKey(orgId, key), value, options);
 }

package/dist/settings/store.d.ts

@@ -9,6 +9,14 @@ export interface StoreReadOptions {
     transaction?: DbExec;
 }
 export declare function getSetting(key: string, options?: StoreReadOptions): Promise<Record<string, unknown> | null>;
+export type SettingEntry = {
+    found: false;
+} | {
+    found: true;
+    value: unknown;
+};
+/** Like `getSetting`, but a stored JSON `null` is found, not missing. */
+export declare function getSettingEntry(key: string, options?: StoreReadOptions): Promise<SettingEntry>;
 export declare function getSettings(keys: readonly string[], options?: StoreReadOptions): Promise<Map<string, Record<string, unknown> | null>>;
 export interface StoreWriteOptions {
     requestSource?: string;

package/dist/settings/store.js

@@ -63,12 +63,10 @@ export const settingsStore = defineStore({
 export function ensureTable() {
     return settingsStore.ready();
 }
-export async function getSetting(key, options) {
+async function readSettingRaw(key, options) {
     const cache = options?.transaction ? null : requestSettingsCache();
-    if (!options?.bypassCache && cache?.has(key)) {
-        const cached = cache.get(key);
-        return cached == null ? null : JSON.parse(cached);
-    }
+    if (!options?.bypassCache && cache?.has(key))
+        return cache.get(key) ?? null;
     if (!options?.transaction)
         await ensureTable();
     const client = options?.transaction ?? getDbExec();
@@ -80,8 +78,19 @@ export async function getSetting(key, options) {
     const raw = rows.length === 0 ? null : rows[0].value;
     if (!options?.bypassCache)
         cache?.set(key, raw);
+    return raw;
+}
+export async function getSetting(key, options) {
+    const raw = await readSettingRaw(key, options);
     return raw == null ? null : JSON.parse(raw);
 }
+/** Like `getSetting`, but a stored JSON `null` is found, not missing. */
+export async function getSettingEntry(key, options) {
+    const raw = await readSettingRaw(key, options);
+    return raw == null
+        ? { found: false }
+        : { found: true, value: JSON.parse(raw) };
+}
 const SETTINGS_IN_LIST_CHUNK_SIZE = 500;
 function parseSettingValue(key, raw) {
     try {

package/dist/shared/consent.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cookie consent for the regions that need it. The regions and categories
+ * follow builder.io's consent banner: visitors in these countries opt in, and
+ * every other visitor is tracked as before, with no banner.
+ */
+export declare function isConsentRegionCountry(code: string | null | undefined): boolean;
+export declare function isConsentRegionTimeZone(timeZone: string | null | undefined): boolean;
+/**
+ * What the banner asks about. `performance` covers analytics (Google
+ * Analytics, Amplitude); `targeting` covers advertising and attribution (Tag
+ * Manager's ad tags, the referral attribution cookies). Strictly necessary
+ * cookies need no consent.
+ */
+export type ConsentCategory = "performance" | "targeting";
+export type ConsentChoice = Record<ConsentCategory, boolean>;
+/** `consent` shows the banner; `none` tracks as before. */
+export type ConsentRegion = "consent" | "none";
+export declare const CONSENT_COOKIE_NAME = "an_consent";
+/** Asked again a year later, like builder.io. */
+export declare const CONSENT_COOKIE_LIFETIME_SECONDS: number;
+export declare const CONSENT_REGION_PATH = "/_agent-native/auth/consent-region";
+export declare const CONSENT_PATH = "/_agent-native/auth/consent";
+/**
+ * One choice covers the site and every app on agent-native.com. The browser
+ * and the server must agree, or the two copies become two cookies.
+ */
+export declare function consentCookieDomain(hostname: string): string | null;
+/** `1.p1.t0`: version, then one flag per category. */
+export declare function serializeConsent(choice: ConsentChoice): string;
+/** The stored choice, or `null` when there is none this version can read. */
+export declare function parseConsent(value: string | null | undefined): ConsentChoice | null;