@oxy-hq/sdk 2.0.1 → 2.3.0

package/dist/index.cjs

@@ -28,8 +28,90 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 let react = require("react");
-react = __toESM(react);
+react = __toESM(react, 1);
+let react_jsx_runtime = require("react/jsx-runtime");
 
+//#region src/anomalies.ts
+/**
+* Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`
+* rather than instantiating directly — the getter wires the request helper
+* so auth, timeout, and branch propagation come along for free.
+*
+* @example
+* ```typescript
+* const { anomalies } = await client.anomalies.list({ status: "new" });
+* for (const a of anomalies) {
+*   console.log(a.label ?? a.measure, a.severity, a.z_score.toFixed(2));
+* }
+* ```
+*/
+var AnomaliesClient = class {
+	constructor(config, request) {
+		this.config = config;
+		this.request = request;
+	}
+	path(suffix) {
+		return `/${this.config.projectId}/semantic/anomalies${suffix}`;
+	}
+	buildQuery(extra = {}) {
+		const params = { ...extra };
+		if (this.config.branch) params.branch = this.config.branch;
+		const qs = new URLSearchParams(params).toString();
+		return qs ? `?${qs}` : "";
+	}
+	/**
+	* List anomalies in the inbox, newest first.
+	*
+	* @example
+	* ```typescript
+	* // Open / unresolved anomalies only
+	* const { anomalies } = await client.anomalies.list({ status: "new" });
+	* ```
+	*/
+	async list(options = {}) {
+		const extra = {};
+		if (options.status) extra.status = options.status;
+		if (options.limit) extra.limit = String(options.limit);
+		return this.request(this.path(this.buildQuery(extra)));
+	}
+	/**
+	* Trigger a full scan. Iterates every `.monitor.yml` entry in the
+	* workspace, runs the detector, and upserts matching rows into the
+	* inbox. Returns counts of scanned / failed / persisted.
+	*
+	* @example
+	* ```typescript
+	* // Scan against a known-good reference date (matches the seed dataset)
+	* const result = await client.anomalies.scan({ as_of: "2025-12-15" });
+	* console.log(`${result.anomalies_persisted} anomalies detected`);
+	* ```
+	*/
+	async scan(options = {}) {
+		const extra = {};
+		if (options.as_of) extra.as_of = options.as_of;
+		return this.request(this.path(`/scan${this.buildQuery(extra)}`), { method: "POST" });
+	}
+	/**
+	* Update an anomaly's status (acknowledge / dismiss / re-open).
+	*/
+	async updateStatus(anomalyId, status) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/${encodeURIComponent(anomalyId)}/status${query}`), {
+			method: "POST",
+			body: JSON.stringify({ status })
+		});
+	}
+	/**
+	* Run the metric-tree `explain` for an anomaly and cache the result on
+	* the row. Subsequent calls return the cached `ExplainResult` instantly.
+	*/
+	async explain(anomalyId) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/${encodeURIComponent(anomalyId)}/explain${query}`), { method: "POST" });
+	}
+};
+
+//#endregion
 //#region src/customer-app/logger.ts
 let activeLogger = createConsoleLogger();
 /** Replace the global logger. Pass `null` to silence everything. */
@@ -94,6 +176,52 @@ async function getCustomerAppDebug(resolved) {
 
 //#endregion
 //#region src/customer-app/errors.ts
+/**
+* Error thrown by all customer-app hooks when an API call returns a
+* non-2xx response. Carries the structured `code` + `hint` the server
+* emits so bundle UIs can render an actionable message instead of
+* "404: { ...json... }".
+*/
+var OxyApiError = class extends Error {
+	constructor(opts) {
+		const base = opts.message || `HTTP ${opts.status}`;
+		const code = opts.code ? ` [${opts.code}]` : "";
+		const hint = opts.hint ? `\n\n${opts.hint}` : "";
+		super(`${base}${code}${hint}`);
+		this.name = "OxyApiError";
+		this.status = opts.status;
+		this.code = opts.code ?? null;
+		this.hint = opts.hint ?? null;
+	}
+};
+/**
+* Read a non-2xx response from oxy and return an `OxyApiError`.
+* Parses the JSON envelope when present; falls back to raw text
+* (truncated to 240 chars so a runaway HTML error page doesn't
+* dominate the bundle UI).
+*/
+async function apiErrorFromResponse(resp) {
+	let body;
+	let raw = "";
+	try {
+		raw = await resp.text();
+		body = raw ? JSON.parse(raw) : void 0;
+	} catch {}
+	if (body && typeof body === "object") {
+		const b = body;
+		return new OxyApiError({
+			status: resp.status,
+			message: typeof b.message === "string" ? b.message : `HTTP ${resp.status}`,
+			code: typeof b.code === "string" ? b.code : null,
+			hint: typeof b.hint === "string" ? b.hint : null
+		});
+	}
+	const snippet = raw.length > 240 ? `${raw.slice(0, 237)}…` : raw;
+	return new OxyApiError({
+		status: resp.status,
+		message: snippet || `HTTP ${resp.status}`
+	});
+}
 const ARCH_DOC = "internal-docs/customer-apps.md";
 /** Interpret a thrown error as a structured report for UI display. */
 function interpretCustomerAppError(err) {
@@ -284,13 +412,174 @@ function validateManifest(raw, url) {
 		name: typeof raw.name === "string" ? raw.name : void 0,
 		slug: raw.slug,
 		orgSlug: typeof raw.orgSlug === "string" ? raw.orgSlug : void 0,
-		projectId: typeof raw.projectId === "string" ? raw.projectId : void 0
+		projectId: typeof raw.projectId === "string" ? raw.projectId : void 0,
+		functions: raw.functions !== void 0 ? validateFunctions(raw.functions) : void 0
 	};
 }
+const FUNCTION_NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+/**
+* Validate the optional `functions` map. Each key is a function name;
+* each value declares how the function is invoked. Mirrors the
+* server-side validation in `customer_apps_publish.rs` so a bad
+* manifest fails at build, not at publish.
+*/
+function validateFunctions(raw) {
+	if (!isRecord(raw)) throw new Error("oxy-app.json: `functions` must be an object keyed by function name");
+	const out = {};
+	for (const [fnName, value] of Object.entries(raw)) {
+		if (!FUNCTION_NAME_RE.test(fnName)) throw new Error(`oxy-app.json: function name "${fnName}" must match ^[a-z][a-z0-9-]{0,63}$`);
+		if (!isRecord(value)) throw new Error(`oxy-app.json: function "${fnName}" must be an object`);
+		const fn = {};
+		if (value.entry !== void 0) {
+			if (typeof value.entry !== "string" || !value.entry.trim()) throw new Error(`oxy-app.json: function "${fnName}" \`entry\` must be a non-empty string`);
+			fn.entry = value.entry;
+		}
+		if (value.schedule !== void 0) {
+			if (typeof value.schedule !== "string" || !value.schedule.trim()) throw new Error(`oxy-app.json: function "${fnName}" \`schedule\` must be a cron string`);
+			fn.schedule = value.schedule;
+		}
+		if (value.timezone !== void 0) {
+			if (typeof value.timezone !== "string") throw new Error(`oxy-app.json: function "${fnName}" \`timezone\` must be a string`);
+			fn.timezone = value.timezone;
+		}
+		if (value.route !== void 0) {
+			if (typeof value.route !== "boolean") throw new Error(`oxy-app.json: function "${fnName}" \`route\` must be a boolean`);
+			fn.route = value.route;
+		}
+		if (value.airwayStep !== void 0) {
+			const step = value.airwayStep;
+			if (!isRecord(step) || typeof step.pipeline !== "string" || typeof step.resource !== "string") throw new Error(`oxy-app.json: function "${fnName}" \`airwayStep\` must be { pipeline, resource }`);
+			fn.airwayStep = {
+				pipeline: step.pipeline,
+				resource: step.resource
+			};
+		}
+		if (value.timeoutSeconds !== void 0) {
+			const t = value.timeoutSeconds;
+			if (typeof t !== "number" || !Number.isInteger(t) || t < 1 || t > 300) throw new Error(`oxy-app.json: function "${fnName}" \`timeoutSeconds\` must be an integer in [1, 300]`);
+			fn.timeoutSeconds = t;
+		}
+		if (value.cache !== void 0) {
+			const c = value.cache;
+			if (!isRecord(c)) throw new Error(`oxy-app.json: function "${fnName}" \`cache\` must be an object`);
+			if (c.ttlSeconds !== void 0) {
+				const ttl = c.ttlSeconds;
+				if (typeof ttl !== "number" || !Number.isInteger(ttl) || ttl < 1) throw new Error(`oxy-app.json: function "${fnName}" \`cache.ttlSeconds\` must be a positive integer`);
+				fn.cache = { ttlSeconds: ttl };
+			}
+		}
+		if (value.retries !== void 0) {
+			const r = value.retries;
+			if (!isRecord(r)) throw new Error(`oxy-app.json: function "${fnName}" \`retries\` must be an object`);
+			const retries = {};
+			for (const key of [
+				"maxAttempts",
+				"minTimeoutMs",
+				"maxTimeoutMs"
+			]) {
+				const n = r[key];
+				if (n !== void 0) {
+					if (typeof n !== "number" || !Number.isInteger(n) || n < 1) throw new Error(`oxy-app.json: function "${fnName}" \`retries.${key}\` must be a positive integer`);
+					retries[key] = n;
+				}
+			}
+			fn.retries = retries;
+		}
+		if (value.inputExample !== void 0) fn.inputExample = value.inputExample;
+		const hasSchedule = fn.schedule !== void 0;
+		const hasAirway = fn.airwayStep !== void 0;
+		if (!(fn.route ?? !(hasSchedule || hasAirway)) && !hasSchedule && !hasAirway) throw new Error(`oxy-app.json: function "${fnName}" must enable at least one of route/schedule/airwayStep`);
+		out[fnName] = fn;
+	}
+	return out;
+}
 function isRecord(v) {
 	return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
+//#endregion
+//#region src/customer-app/function-invoke.ts
+const inflight$1 = /* @__PURE__ */ new Map();
+/**
+* Dedup key for an invocation: function name + its (stable-serialized) body,
+* joined by a newline. Function names are `[a-z][a-z0-9-]*` (no newline), so
+* the separator can never collide with a name.
+*/
+function functionInvokeKey(name, body) {
+	return `${name}\n${JSON.stringify(body ?? {})}`;
+}
+/**
+* Run `run()` unless an identical invocation is already in flight, in which
+* case share its promise. The entry is removed once the promise settles — so
+* this dedups concurrency only, it does NOT memoize the result.
+*/
+function sharedFunctionInvoke(key, run) {
+	const existing = inflight$1.get(key);
+	if (existing) return existing;
+	const p = run().finally(() => {
+		inflight$1.delete(key);
+	});
+	inflight$1.set(key, p);
+	return p;
+}
+
+//#endregion
+//#region src/customer-app/function-sse.ts
+/**
+* Read a `text/event-stream` function response to completion. Resolves with the
+* decoded result + captured logs, or rejects (with `.logs` attached) on an
+* `event: error` frame / a stream that ends without a terminal event.
+*/
+async function readFunctionSseStream(resp) {
+	const reader = resp.body?.getReader();
+	if (!reader) throw new Error("function response has no body stream");
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let dataPayload = "";
+	const logs = [];
+	const handleFrame = (frame) => {
+		let event = "message";
+		let data = "";
+		for (const line of frame.split("\n")) if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) data += line.slice(5).trim();
+		if (event === "log") try {
+			const l = JSON.parse(data);
+			logs.push({
+				level: String(l.level ?? "info"),
+				message: String(l.message ?? "")
+			});
+		} catch {}
+		else if (event === "data") dataPayload = data;
+		else if (event === "done") return {
+			done: true,
+			value: dataPayload ? JSON.parse(dataPayload) : null
+		};
+		else if (event === "error") {
+			const payload = data ? JSON.parse(data) : {};
+			const err = new Error(payload.message || payload.error || "function invocation failed");
+			err.name = payload.error || "FunctionError";
+			err.logs = logs;
+			throw err;
+		}
+	};
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let sep;
+		while ((sep = buffer.indexOf("\n\n")) !== -1) {
+			const frame = buffer.slice(0, sep);
+			buffer = buffer.slice(sep + 2);
+			const result = handleFrame(frame);
+			if (result) return {
+				value: result.value,
+				logs
+			};
+		}
+	}
+	throw new Error("function stream ended without a terminal event");
+}
+
 //#endregion
 //#region src/customer-app/interpolate.ts
 /**
@@ -355,6 +644,50 @@ function isSafeLinkHref(raw) {
 	return lower.startsWith("http://") || lower.startsWith("https://") || lower.startsWith("mailto:");
 }
 
+//#endregion
+//#region src/customer-app/query-cache.ts
+const SWR_TTL_MS = 3e4;
+const inflight = /* @__PURE__ */ new Map();
+const cache = /* @__PURE__ */ new Map();
+function queryKey(projectId, db, sql) {
+	return `${projectId} ${db ?? ""} ${sql}`;
+}
+function getCached(projectId, sql, db) {
+	const e = cache.get(queryKey(projectId, db, sql));
+	return e && Date.now() - e.at < SWR_TTL_MS ? e.data : void 0;
+}
+/** Fetch with in-flight dedup + cache. `force` bypasses the fresh-cache
+*  short-circuit (used by refetch) but still dedupes a concurrent in-flight. */
+async function sharedQuery(fetcher, projectId, sql, db, opts = {}) {
+	const key = queryKey(projectId, db, sql);
+	if (!opts.force) {
+		const fresh = getCached(projectId, sql, db);
+		if (fresh) return fresh;
+	}
+	const existing = inflight.get(key);
+	if (existing) return existing;
+	const body = JSON.stringify({
+		sql,
+		...db ? { database: db } : {}
+	});
+	const p = (async () => {
+		const resp = await fetcher(`/api/projects/${projectId}/query`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body
+		});
+		if (!resp.ok) throw await apiErrorFromResponse(resp);
+		const data = await resp.json();
+		cache.set(key, {
+			at: Date.now(),
+			data
+		});
+		return data;
+	})().finally(() => inflight.delete(key));
+	inflight.set(key, p);
+	return p;
+}
+
 //#endregion
 //#region src/customer-app/react.tsx
 function defaultFetcher(input, init) {
@@ -396,26 +729,55 @@ function OxyAppProvider(props) {
 	}, [manifestOptions, fetcher]);
 	if (state.status === "error" && state.error) {
 		const err = state.error;
-		return /* @__PURE__ */ react.createElement(OxyAppContext.Provider, { value: state }, errorFallback ? errorFallback(err) : defaultErrorFallback(err));
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OxyAppContext.Provider, {
+			value: state,
+			children: errorFallback ? errorFallback(err) : defaultErrorFallback(err)
+		});
 	}
-	if (state.status === "loading") return /* @__PURE__ */ react.createElement(OxyAppContext.Provider, { value: state }, fallback ?? null);
-	return /* @__PURE__ */ react.createElement(OxyAppContext.Provider, { value: state }, children);
+	if (state.status === "loading") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OxyAppContext.Provider, {
+		value: state,
+		children: fallback ?? null
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OxyAppContext.Provider, {
+		value: state,
+		children
+	});
 }
 function defaultErrorFallback(err) {
-	return /* @__PURE__ */ react.createElement("div", { style: {
-		margin: "2rem auto",
-		maxWidth: "640px",
-		padding: "1rem",
-		border: "1px solid #fca5a5",
-		background: "#fee2e2",
-		color: "#991b1b",
-		borderRadius: "8px",
-		fontFamily: "system-ui, -apple-system, sans-serif",
-		fontSize: "14px"
-	} }, /* @__PURE__ */ react.createElement("div", { style: { fontWeight: 600 } }, err.title), /* @__PURE__ */ react.createElement("pre", { style: {
-		fontSize: "12px",
-		marginTop: "4px"
-	} }, err.message), /* @__PURE__ */ react.createElement("div", { style: { marginTop: "12px" } }, /* @__PURE__ */ react.createElement("strong", null, "What to try:"), " ", err.hint));
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		style: {
+			margin: "2rem auto",
+			maxWidth: "640px",
+			padding: "1rem",
+			border: "1px solid #fca5a5",
+			background: "#fee2e2",
+			color: "#991b1b",
+			borderRadius: "8px",
+			fontFamily: "system-ui, -apple-system, sans-serif",
+			fontSize: "14px"
+		},
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				style: { fontWeight: 600 },
+				children: err.title
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+				style: {
+					fontSize: "12px",
+					marginTop: "4px"
+				},
+				children: err.message
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: { marginTop: "12px" },
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "What to try:" }),
+					" ",
+					err.hint
+				]
+			})
+		]
+	});
 }
 /**
 * Emit a one-time `console.warn` the first time a beta hook is
@@ -430,58 +792,6 @@ function warnBetaOnce(name) {
 	if (typeof console !== "undefined" && typeof console.warn === "function") console.warn(`[@oxy-hq/sdk] \`${name}\` is in beta — interface and behavior may change. See https://github.com/oxy-hq/customer-apps for caveats and the migration guide.`);
 }
 /**
-* Error thrown by all customer-app hooks when an API call returns a
-* non-2xx response. Carries the structured `code` + `hint` the server
-* emits so bundle UIs can render an actionable message instead of
-* "404: { ...json... }".
-*
-* The server contract is documented in
-* `crates/app/src/server/api/projects/agent_ask.rs` and
-* `procedure_run.rs` — both emit `{ message, code?, hint? }` as JSON.
-* Hooks that previously wrapped the raw text in `new Error()` now
-* throw this type instead.
-*/
-var OxyApiError = class extends Error {
-	constructor(opts) {
-		const base = opts.message || `HTTP ${opts.status}`;
-		const code = opts.code ? ` [${opts.code}]` : "";
-		const hint = opts.hint ? `\n\n${opts.hint}` : "";
-		super(`${base}${code}${hint}`);
-		this.name = "OxyApiError";
-		this.status = opts.status;
-		this.code = opts.code ?? null;
-		this.hint = opts.hint ?? null;
-	}
-};
-/**
-* Read a non-2xx response from oxy and return an `OxyApiError`.
-* Parses the JSON envelope when present; falls back to raw text
-* (truncated to 240 chars so a runaway HTML error page doesn't
-* dominate the bundle UI).
-*/
-async function apiErrorFromResponse(resp) {
-	let body;
-	let raw = "";
-	try {
-		raw = await resp.text();
-		body = raw ? JSON.parse(raw) : void 0;
-	} catch {}
-	if (body && typeof body === "object") {
-		const b = body;
-		return new OxyApiError({
-			status: resp.status,
-			message: typeof b.message === "string" ? b.message : `HTTP ${resp.status}`,
-			code: typeof b.code === "string" ? b.code : null,
-			hint: typeof b.hint === "string" ? b.hint : null
-		});
-	}
-	const snippet = raw.length > 240 ? `${raw.slice(0, 237)}…` : raw;
-	return new OxyApiError({
-		status: resp.status,
-		message: snippet || `HTTP ${resp.status}`
-	});
-}
-/**
 * Read the resolved manifest from context. Throws if called outside
 * `<OxyAppProvider>` — that's a programmer error worth surfacing
 * loudly, not silently swallowing.
@@ -535,36 +845,35 @@ function useQuery(input, opts = {}) {
 			} : s);
 			return;
 		}
-		const ctrl = new AbortController();
 		let cancelled = false;
+		const cached = getCached(projectId, sqlWithParams, input.database);
+		if (cached && nonce === 0) {
+			const { columns, rows } = cached;
+			const objects = rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]])));
+			setState({
+				rows: objects,
+				columns,
+				loading: false,
+				error: null
+			});
+			return;
+		}
 		setState((s) => ({
 			...s,
 			loading: true,
 			error: null
 		}));
-		const body = JSON.stringify({
-			sql: sqlWithParams,
-			...input.database ? { database: input.database } : {}
-		});
-		fetcher(`/api/projects/${projectId}/query`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body,
-			signal: ctrl.signal
-		}).then(async (resp) => {
-			if (!resp.ok) throw await apiErrorFromResponse(resp);
-			return resp.json();
-		}).then(({ columns, rows }) => {
+		sharedQuery(fetcher, projectId, sqlWithParams, input.database, { force: nonce > 0 }).then(({ columns, rows }) => {
 			if (cancelled) return;
+			const objects = rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]])));
 			setState({
-				rows: rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]]))),
+				rows: objects,
 				columns,
 				loading: false,
 				error: null
 			});
 		}).catch((err) => {
 			if (cancelled) return;
-			if (err instanceof DOMException && err.name === "AbortError") return;
 			setState((s) => ({
 				...s,
 				loading: false,
@@ -573,7 +882,6 @@ function useQuery(input, opts = {}) {
 		});
 		return () => {
 			cancelled = true;
-			ctrl.abort();
 		};
 	}, [
 		enabled,
@@ -592,6 +900,81 @@ function useQuery(input, opts = {}) {
 	};
 }
 /**
+* Imperative hook for invoking an Oxy Function by name.
+*
+* ```tsx
+* const refresh = useFunction("refresh-sales");
+* <button disabled={refresh.isLoading} onClick={() => refresh.invoke({ full: true })}>
+*   Refresh
+* </button>
+* ```
+*/
+function useFunction(name) {
+	const ctx = react.useContext(OxyAppContext);
+	if (!ctx) throw new Error("useFunction must be called inside <OxyAppProvider>");
+	const fetcher = ctx.fetcher;
+	const resolved = ctx.resolved;
+	const [state, setState] = react.useState({
+		data: null,
+		isLoading: false,
+		error: null,
+		logs: []
+	});
+	return {
+		invoke: react.useCallback(async (body, opts) => {
+			if (!resolved) throw new Error("useFunction.invoke called before the manifest finished loading. Render behind the provider's `fallback` until ready.");
+			const { orgSlug, appSlug, apiBaseUrl } = resolved;
+			const url = `${apiBaseUrl || ""}/customer-apps/${encodeURIComponent(orgSlug)}/${encodeURIComponent(appSlug)}/fn/${encodeURIComponent(name)}`;
+			setState((s) => ({
+				...s,
+				isLoading: true,
+				error: null
+			}));
+			try {
+				const headers = {
+					"content-type": "application/json",
+					accept: "text/event-stream"
+				};
+				if (opts?.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
+				const result = await sharedFunctionInvoke(functionInvokeKey(name, body), async () => {
+					const resp = await fetcher(url, {
+						method: "POST",
+						headers,
+						body: JSON.stringify(body ?? {})
+					});
+					if (!resp.ok && resp.status !== 200) throw await apiErrorFromResponse(resp);
+					return readFunctionSseStream(resp);
+				});
+				setState({
+					data: result.value,
+					isLoading: false,
+					error: null,
+					logs: result.logs
+				});
+				return result.value;
+			} catch (err) {
+				const e = err instanceof Error ? err : new Error(String(err));
+				const logs = e.logs ?? [];
+				setState((s) => ({
+					...s,
+					isLoading: false,
+					error: e,
+					logs
+				}));
+				throw e;
+			}
+		}, [
+			resolved,
+			fetcher,
+			name
+		]),
+		data: state.data,
+		isLoading: state.isLoading,
+		error: state.error,
+		logs: state.logs
+	};
+}
+/**
 * Run a semantic-layer query against the project's `.view.yml` /
 * `.topic.yml` definitions. The server compiles to SQL and executes
 * through the same connector path as `useQuery`, so result shape
@@ -639,7 +1022,8 @@ function useSemanticQuery(input, opts = {}) {
 			filters: input.filters ?? [],
 			...input.limit != null ? { limit: input.limit } : {}
 		});
-		fetcher(`/api/projects/${projectId}/semantic-query${debug ? "?debug=1" : ""}`, {
+		const url = `/api/projects/${projectId}/semantic-query${debug ? "?debug=1" : ""}`;
+		fetcher(url, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body,
@@ -649,8 +1033,9 @@ function useSemanticQuery(input, opts = {}) {
 			return resp.json();
 		}).then(({ columns, rows, truncated, sql }) => {
 			if (cancelled) return;
+			const objects = rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]])));
 			setState({
-				rows: rows.map((r) => Object.fromEntries(columns.map((c, i) => [c, r[i]]))),
+				rows: objects,
 				columns,
 				truncated,
 				sql: sql ?? null,
@@ -1037,7 +1422,7 @@ function parseSseData(raw) {
 *  uniformly. New types added upstream don't surface as artifacts
 *  until added here — that's intentional, the renderer needs to
 *  know how to display each. */
-const SQL_EVENT_TYPES = new Set([
+const SQL_EVENT_TYPES = /* @__PURE__ */ new Set([
 	"query_executed",
 	"query_generated",
 	"verified_sql",
@@ -1166,6 +1551,82 @@ function sleep(ms, signal) {
 	});
 }
 /**
+* Engineer-tagged usage event. Free-form `event_name` (≤ 64 chars,
+* `[a-z][a-z0-9-]*` validated server-side) + optional JSON `payload`
+* (object, ≤ 4 KiB serialized). Surfaces in the admin Activity tab
+* grouped by name, with drill-down into recent occurrences.
+*
+* The handler returned by [`useTrackEvent`] is **fire-and-forget**:
+* it enqueues the event into an in-memory batch flushed every second
+* (and on `pagehide` so a navigation away doesn't drop the tail).
+* No await semantics — call it inline from a click handler without
+* awaiting it. Server-side validation errors are logged to the
+* console; the call site doesn't need to handle them.
+*
+* Example:
+* ```tsx
+* const track = useTrackEvent();
+* <button
+*   onClick={() => {
+*     track("export-clicked", { format: "csv", rowCount });
+*     doExport();
+*   }}
+* >Export</button>
+* ```
+*
+* Rate-limited at 60/min per (user, app) on the server. A burst that
+* trips the limit drops the excess events with a console warning;
+* within-limit events are unaffected.
+*/
+function useTrackEvent() {
+	const { projectId, fetcher } = useOxyApp();
+	const queueRef = react.useRef([]);
+	const flushTimerRef = react.useRef(null);
+	const flush = react.useCallback(() => {
+		flushTimerRef.current = null;
+		if (!projectId) return;
+		const batch = queueRef.current;
+		if (batch.length === 0) return;
+		queueRef.current = [];
+		for (const evt of batch) {
+			const url = `/api/customer-apps/${projectId}/events`;
+			const body = JSON.stringify(evt);
+			try {
+				if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && document.visibilityState === "hidden") navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+				else fetcher(url, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body
+				}).catch((e) => {
+					console.warn("[oxy] useTrackEvent flush failed:", e);
+				});
+			} catch (e) {
+				console.warn("[oxy] useTrackEvent enqueue failed:", e);
+			}
+		}
+	}, [projectId, fetcher]);
+	react.useEffect(() => {
+		if (typeof window === "undefined") return;
+		const onHide = () => flush();
+		window.addEventListener("pagehide", onHide);
+		return () => {
+			window.removeEventListener("pagehide", onHide);
+			flush();
+			if (flushTimerRef.current !== null) {
+				clearTimeout(flushTimerRef.current);
+				flushTimerRef.current = null;
+			}
+		};
+	}, [flush]);
+	return react.useCallback((name, payload) => {
+		queueRef.current.push({
+			event_name: name,
+			payload: payload ?? {}
+		});
+		if (flushTimerRef.current === null) flushTimerRef.current = setTimeout(flush, 1e3);
+	}, [flush]);
+}
+/**
 * Renders an agent run's answer + artifacts + thread link as a
 * single block. The default styling is intentionally neutral
 * (system fonts, gray surfaces) so it blends into any bundle.
@@ -1187,25 +1648,55 @@ function OxyAnswer(props) {
 	const isRunning = state === "running";
 	const isFailed = state === "failed";
 	const needsClarification = state === "needs_clarification";
-	return /* @__PURE__ */ react.createElement("div", {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className,
-		style: styles.answerWrap
-	}, isRunning && answer === null ? /* @__PURE__ */ react.createElement("div", { style: styles.statusRow }, /* @__PURE__ */ react.createElement("span", {
-		style: styles.spinner,
-		"aria-hidden": "true"
-	}), /* @__PURE__ */ react.createElement("span", { style: styles.statusText }, "Thinking…")) : null, artifacts.length > 0 ? /* @__PURE__ */ react.createElement("div", { style: styles.artifactList }, artifacts.map((a) => /* @__PURE__ */ react.createElement(SqlArtifactBlock, {
-		key: a.id,
-		artifact: a,
-		maxRows: maxArtifactRows
-	}))) : null, answer ? /* @__PURE__ */ react.createElement("div", { style: styles.markdown }, /* @__PURE__ */ react.createElement(MarkdownText, { text: answer })) : null, needsClarification && clarification ? /* @__PURE__ */ react.createElement("div", { style: styles.clarification }, /* @__PURE__ */ react.createElement("strong", null, "Agent needs clarification:"), /* @__PURE__ */ react.createElement("div", { style: { marginTop: 4 } }, clarification)) : null, isFailed && error ? /* @__PURE__ */ react.createElement(ErrorBlock, { error }) : null, threadUrl && (answer || artifacts.length > 0) ? /* @__PURE__ */ react.createElement("div", { style: styles.threadLinkRow }, /* @__PURE__ */ react.createElement("a", {
-		href: threadUrl,
-		target: "_blank",
-		rel: "noreferrer noopener",
-		style: styles.threadLink
-	}, threadLinkLabel, " →"), /* @__PURE__ */ react.createElement("span", {
-		style: styles.betaBadge,
-		title: "Thread linking is in beta — see docs"
-	}, "beta")) : null);
+		style: styles.answerWrap,
+		children: [
+			isRunning && answer === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: styles.statusRow,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.spinner,
+					"aria-hidden": "true"
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.statusText,
+					children: "Thinking…"
+				})]
+			}) : null,
+			artifacts.length > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				style: styles.artifactList,
+				children: artifacts.map((a) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SqlArtifactBlock, {
+					artifact: a,
+					maxRows: maxArtifactRows
+				}, a.id))
+			}) : null,
+			answer ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				style: styles.markdown,
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MarkdownText, { text: answer })
+			}) : null,
+			needsClarification && clarification ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: styles.clarification,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "Agent needs clarification:" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					style: { marginTop: 4 },
+					children: clarification
+				})]
+			}) : null,
+			isFailed && error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ErrorBlock, { error }) : null,
+			threadUrl && (answer || artifacts.length > 0) ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: styles.threadLinkRow,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("a", {
+					href: threadUrl,
+					target: "_blank",
+					rel: "noreferrer noopener",
+					style: styles.threadLink,
+					children: [threadLinkLabel, " →"]
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.betaBadge,
+					title: "Thread linking is in beta — see docs",
+					children: "beta"
+				})]
+			}) : null
+		]
+	});
 }
 /**
 * Complete drop-in chat surface. One agent, one input, one answer
@@ -1229,37 +1720,48 @@ function OxyChat(props) {
 		if (!q || run.state === "running") return;
 		run.ask(q);
 	}, [question, run]);
-	return /* @__PURE__ */ react.createElement("div", {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className,
-		style: styles.chatWrap
-	}, /* @__PURE__ */ react.createElement("form", {
-		onSubmit: submit,
-		style: styles.chatForm
-	}, /* @__PURE__ */ react.createElement("input", {
-		type: "text",
-		value: question,
-		onChange: (e) => setQuestion(e.target.value),
-		placeholder,
-		disabled: run.state === "running",
-		style: styles.chatInput,
-		"aria-label": "Question"
-	}), /* @__PURE__ */ react.createElement("button", {
-		type: "submit",
-		disabled: run.state === "running" || question.trim() === "",
-		style: styles.chatSubmit
-	}, run.state === "running" ? "…" : submitLabel), run.state === "running" ? /* @__PURE__ */ react.createElement("button", {
-		type: "button",
-		onClick: run.cancel,
-		style: styles.chatCancel
-	}, "Stop") : null), run.state === "idle" ? emptyState ?? /* @__PURE__ */ react.createElement("div", { style: styles.emptyState }, "Ask a question to get started.") : /* @__PURE__ */ react.createElement(OxyAnswer, {
-		answer: run.answer,
-		artifacts: run.artifacts,
-		state: run.state,
-		clarification: run.clarification,
-		error: run.error,
-		threadUrl: run.threadUrl,
-		maxArtifactRows
-	}));
+		style: styles.chatWrap,
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("form", {
+			onSubmit: submit,
+			style: styles.chatForm,
+			children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+					type: "text",
+					value: question,
+					onChange: (e) => setQuestion(e.target.value),
+					placeholder,
+					disabled: run.state === "running",
+					style: styles.chatInput,
+					"aria-label": "Question"
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "submit",
+					disabled: run.state === "running" || question.trim() === "",
+					style: styles.chatSubmit,
+					children: run.state === "running" ? "…" : submitLabel
+				}),
+				run.state === "running" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+					type: "button",
+					onClick: run.cancel,
+					style: styles.chatCancel,
+					children: "Stop"
+				}) : null
+			]
+		}), run.state === "idle" ? emptyState ?? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			style: styles.emptyState,
+			children: "Ask a question to get started."
+		}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(OxyAnswer, {
+			answer: run.answer,
+			artifacts: run.artifacts,
+			state: run.state,
+			clarification: run.clarification,
+			error: run.error,
+			threadUrl: run.threadUrl,
+			maxArtifactRows
+		})]
+	});
 }
 function SqlArtifactBlock(props) {
 	const { artifact, maxRows } = props;
@@ -1268,17 +1770,53 @@ function SqlArtifactBlock(props) {
 	const truncated = results ? results.rows.length > maxRows : false;
 	const visibleRows = results ? results.rows.slice(0, maxRows) : [];
 	const sourceLabel = artifact.source === "verified_sql" ? "Verified query" : artifact.source === "semantic_query" ? "Semantic query" : artifact.source === "omni_query" ? "Omni query" : "Query";
-	return /* @__PURE__ */ react.createElement("div", { style: styles.artifact }, /* @__PURE__ */ react.createElement("button", {
-		type: "button",
-		onClick: () => setOpen((o) => !o),
-		style: styles.artifactHeader
-	}, /* @__PURE__ */ react.createElement("span", { style: styles.artifactBadge }, sourceLabel), /* @__PURE__ */ react.createElement("span", { style: styles.artifactSummary }, results ? `${results.rowCount} row${results.rowCount === 1 ? "" : "s"}` : artifact.error ? "execution failed" : "SQL only"), /* @__PURE__ */ react.createElement("span", { style: styles.artifactToggle }, open ? "Hide" : "Show")), open ? /* @__PURE__ */ react.createElement("div", null, /* @__PURE__ */ react.createElement("pre", { style: styles.sqlBlock }, artifact.sql), artifact.error ? /* @__PURE__ */ react.createElement("div", { style: styles.error }, artifact.error) : results ? /* @__PURE__ */ react.createElement("div", { style: styles.resultsWrap }, /* @__PURE__ */ react.createElement("table", { style: styles.resultsTable }, /* @__PURE__ */ react.createElement("thead", null, /* @__PURE__ */ react.createElement("tr", null, results.columns.map((c) => /* @__PURE__ */ react.createElement("th", {
-		key: c,
-		style: styles.resultsTh
-	}, c)))), /* @__PURE__ */ react.createElement("tbody", null, visibleRows.map((row, i) => /* @__PURE__ */ react.createElement("tr", { key: i }, row.map((cell, j) => /* @__PURE__ */ react.createElement("td", {
-		key: j,
-		style: styles.resultsTd
-	}, formatCell(cell))))))), truncated ? /* @__PURE__ */ react.createElement("div", { style: styles.truncatedNote }, "+", results.rows.length - maxRows, " more rows. Open the thread in Oxy to see all.") : null) : null) : null);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		style: styles.artifact,
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+			type: "button",
+			onClick: () => setOpen((o) => !o),
+			style: styles.artifactHeader,
+			children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.artifactBadge,
+					children: sourceLabel
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.artifactSummary,
+					children: results ? `${results.rowCount} row${results.rowCount === 1 ? "" : "s"}` : artifact.error ? "execution failed" : "SQL only"
+				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					style: styles.artifactToggle,
+					children: open ? "Hide" : "Show"
+				})
+			]
+		}), open ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+			style: styles.sqlBlock,
+			children: artifact.sql
+		}), artifact.error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			style: styles.error,
+			children: artifact.error
+		}) : results ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			style: styles.resultsWrap,
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("table", {
+				style: styles.resultsTable,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("thead", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tr", { children: results.columns.map((c) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("th", {
+					style: styles.resultsTh,
+					children: c
+				}, c)) }) }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tbody", { children: visibleRows.map((row, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tr", { children: row.map((cell, j) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
+					style: styles.resultsTd,
+					children: formatCell(cell)
+				}, j)) }, i)) })]
+			}), truncated ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: styles.truncatedNote,
+				children: [
+					"+",
+					results.rows.length - maxRows,
+					" more rows. Open the thread in Oxy to see all."
+				]
+			}) : null]
+		}) : null] }) : null]
+	});
 }
 function formatCell(value) {
 	if (value === null || value === void 0) return "—";
@@ -1293,16 +1831,36 @@ function formatCell(value) {
 */
 function ErrorBlock(props) {
 	const { error } = props;
-	if (error instanceof OxyApiError) return /* @__PURE__ */ react.createElement("div", { style: styles.error }, /* @__PURE__ */ react.createElement("div", null, /* @__PURE__ */ react.createElement("strong", null, "Run failed:"), " ", error.message.split("\n\n")[0]), error.hint ? /* @__PURE__ */ react.createElement("div", { style: {
-		marginTop: 6,
-		fontWeight: 400,
-		whiteSpace: "pre-wrap"
-	} }, /* @__PURE__ */ react.createElement("strong", null, "Hint:"), " ", error.hint) : null);
-	return /* @__PURE__ */ react.createElement("div", { style: styles.error }, /* @__PURE__ */ react.createElement("strong", null, "Run failed:"), " ", error.message);
+	if (error instanceof OxyApiError) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		style: styles.error,
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", { children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "Run failed:" }),
+			" ",
+			error.message.split("\n\n")[0]
+		] }), error.hint ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			style: {
+				marginTop: 6,
+				fontWeight: 400,
+				whiteSpace: "pre-wrap"
+			},
+			children: [
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "Hint:" }),
+				" ",
+				error.hint
+			]
+		}) : null]
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		style: styles.error,
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "Run failed:" }),
+			" ",
+			error.message
+		]
+	});
 }
 function MarkdownText(props) {
-	const blocks = react.useMemo(() => parseMarkdown(props.text), [props.text]);
-	return /* @__PURE__ */ react.createElement(react.Fragment, null, blocks);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: react.useMemo(() => parseMarkdown(props.text), [props.text]) });
 }
 function parseMarkdown(text) {
 	const lines = text.replace(/\r\n/g, "\n").split("\n");
@@ -1372,27 +1930,23 @@ function parseMarkdown(text) {
 	}
 	return blocks.map((b, idx) => {
 		switch (b.kind) {
-			case "h": {
-				const Tag = `h${b.level}`;
-				const headingStyle = b.level === 1 ? styles.h1 : b.level === 2 ? styles.h2 : styles.h3;
-				return /* @__PURE__ */ react.createElement(Tag, {
-					key: idx,
-					style: headingStyle
-				}, renderInline(b.text));
-			}
-			case "code": return /* @__PURE__ */ react.createElement("pre", {
-				key: idx,
+			case "h": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(`h${b.level}`, {
+				style: b.level === 1 ? styles.h1 : b.level === 2 ? styles.h2 : styles.h3,
+				children: renderInline(b.text)
+			}, idx);
+			case "code": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
 				style: styles.codeBlock,
-				"data-lang": b.lang || void 0
-			}, /* @__PURE__ */ react.createElement("code", null, b.code));
-			case "list": return /* @__PURE__ */ react.createElement("ul", {
-				key: idx,
-				style: styles.list
-			}, b.items.map((item, i) => /* @__PURE__ */ react.createElement("li", { key: i }, renderInline(item))));
-			case "p": return /* @__PURE__ */ react.createElement("p", {
-				key: idx,
-				style: styles.paragraph
-			}, renderInline(b.text));
+				"data-lang": b.lang || void 0,
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: b.code })
+			}, idx);
+			case "list": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+				style: styles.list,
+				children: b.items.map((item, i) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: renderInline(item) }, i))
+			}, idx);
+			case "p": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+				style: styles.paragraph,
+				children: renderInline(b.text)
+			}, idx);
 		}
 	});
 }
@@ -1408,27 +1962,31 @@ function renderInline(text) {
 	const patterns = [
 		{
 			re: /`([^`]+)`/,
-			render: (m) => /* @__PURE__ */ react.createElement("code", { style: styles.inlineCode }, m[1])
+			render: (m) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
+				style: styles.inlineCode,
+				children: m[1]
+			})
 		},
 		{
 			re: /\[([^\]]+)\]\(([^)]+)\)/,
 			render: (m) => {
-				if (isSafeLinkHref(m[2])) return /* @__PURE__ */ react.createElement("a", {
+				if (isSafeLinkHref(m[2])) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
 					href: m[2],
 					target: "_blank",
 					rel: "noreferrer noopener",
-					style: styles.link
-				}, m[1]);
-				return /* @__PURE__ */ react.createElement(react.Fragment, null, m[1]);
+					style: styles.link,
+					children: m[1]
+				});
+				return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: m[1] });
 			}
 		},
 		{
 			re: /\*\*([^*]+)\*\*/,
-			render: (m) => /* @__PURE__ */ react.createElement("strong", null, m[1])
+			render: (m) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: m[1] })
 		},
 		{
 			re: /\*([^*]+)\*/,
-			render: (m) => /* @__PURE__ */ react.createElement("em", null, m[1])
+			render: (m) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("em", { children: m[1] })
 		}
 	];
 	while (remaining.length > 0) {
@@ -1446,7 +2004,7 @@ function renderInline(text) {
 			break;
 		}
 		if (earliest.idx > 0) segments.push(remaining.slice(0, earliest.idx));
-		segments.push(/* @__PURE__ */ react.createElement(react.Fragment, { key: key++ }, earliest.node));
+		segments.push(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(react.Fragment, { children: earliest.node }, key++));
 		remaining = remaining.slice(earliest.idx + earliest.len);
 	}
 	return segments;
@@ -1676,11 +2234,142 @@ const styles = {
 };
 
 //#endregion
+//#region src/metricTree.ts
+/**
+* Client for the `/semantic/metric-tree*` endpoints. Surfaces the four
+* airlayer metric-tree analyses (tree introspection, sensitivity, predict,
+* explain, opportunity) over typed methods.
+*
+* Construction is internal to {@link OxyClient} — call `client.metricTree`
+* to access an instance rather than building one yourself.
+*
+* @example
+* ```typescript
+* const client = await OxyClient.create({ projectId: "...", apiKey: "..." });
+* const tree = await client.metricTree.getTree();
+* const drivers = await client.metricTree.getSensitivity("orders.net_revenue");
+* ```
+*/
+var MetricTreeClient = class {
+	constructor(config, request) {
+		this.config = config;
+		this.request = request;
+	}
+	path(suffix) {
+		return `/${this.config.projectId}/semantic/metric-tree${suffix}`;
+	}
+	buildQuery(extra = {}) {
+		const params = { ...extra };
+		if (this.config.branch) params.branch = this.config.branch;
+		const qs = new URLSearchParams(params).toString();
+		return qs ? `?${qs}` : "";
+	}
+	/**
+	* Fetch the full metric tree, or the subtree rooted at `root`.
+	*
+	* @param root - Optional fully-qualified measure id to root the tree at.
+	* @returns Nodes (measures) and edges (component / driver relationships).
+	*
+	* @example
+	* ```typescript
+	* const tree = await client.metricTree.getTree();
+	* const subtree = await client.metricTree.getTree("orders.net_revenue");
+	* ```
+	*/
+	async getTree(root) {
+		const query = this.buildQuery(root ? { root } : {});
+		return this.request(this.path(query));
+	}
+	/**
+	* Rank the declared drivers of a measure by influence.
+	*
+	* @param measureId - Fully-qualified measure id (`view.measure`).
+	*
+	* @example
+	* ```typescript
+	* const sensitivity = await client.metricTree.getSensitivity("orders.net_revenue");
+	* for (const driver of sensitivity.drivers) {
+	*   console.log(driver.measure, driver.direction, driver.strength);
+	* }
+	* ```
+	*/
+	async getSensitivity(measureId) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/${encodeURIComponent(measureId)}/sensitivity${query}`));
+	}
+	/**
+	* Propagate hypothetical `(measure, delta)` changes upward through the
+	* tree. Returns the estimated impact on every downstream measure.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.metricTree.predict([
+	*   { measure: "marketing_spend.total_spend", delta: 10000 },
+	* ]);
+	* ```
+	*/
+	async predict(changes) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/predict${query}`), {
+			method: "POST",
+			body: JSON.stringify({ changes })
+		});
+	}
+	/**
+	* Period-over-period root-cause decomposition. Recursively splits the
+	* target measure by components and dimensions until the move concentrates.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.metricTree.explain({
+	*   target: "financials.operating_profit",
+	*   time_dimension: "financials.month",
+	*   current_period: ["2025-09-01", "2025-09-30"],
+	*   previous_period: ["2025-08-01", "2025-08-31"],
+	* });
+	* ```
+	*/
+	async explain(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/explain${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
+		});
+	}
+	/**
+	* Size the upside opportunity for a measure by finding underperforming
+	* segments. Skips high-cardinality dimensions and trims the long tail.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.metricTree.findOpportunities({
+	*   target: "orders.net_revenue",
+	*   time_dimension: "orders.order_date",
+	*   period: ["2025-09-01", "2025-09-30"],
+	* });
+	* for (const dim of result.dimensions) {
+	*   console.log(dim.dimension, "+", dim.total_upside);
+	* }
+	* ```
+	*/
+	async findOpportunities(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/opportunity${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
+		});
+	}
+};
+
+//#endregion
+exports.AnomaliesClient = AnomaliesClient;
+exports.MetricTreeClient = MetricTreeClient;
 exports.OxyAnswer = OxyAnswer;
 exports.OxyApiError = OxyApiError;
 exports.OxyAppProvider = OxyAppProvider;
 exports.OxyChat = OxyChat;
 exports._resetCustomerAppManifestCacheForTest = _resetCustomerAppManifestCacheForTest;
+exports.apiErrorFromResponse = apiErrorFromResponse;
 exports.getCustomerAppDebug = getCustomerAppDebug;
 exports.getOxyAppLogger = getOxyAppLogger;
 exports.interpretCustomerAppError = interpretCustomerAppError;
@@ -1688,8 +2377,10 @@ exports.loadCustomerAppManifest = loadCustomerAppManifest;
 exports.readInjectedAppConfig = readInjectedAppConfig;
 exports.setOxyAppLogger = setOxyAppLogger;
 exports.useAgentRun = useAgentRun;
+exports.useFunction = useFunction;
 exports.useProcedureRun = useProcedureRun;
 exports.useQuery = useQuery;
 exports.useResolvedManifest = useResolvedManifest;
 exports.useSemanticQuery = useSemanticQuery;
+exports.useTrackEvent = useTrackEvent;
 //# sourceMappingURL=index.cjs.map