@oxy-hq/sdk 2.11.0 → 2.13.0

package/dist/function-context-D8eyZuw_.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-context-D8eyZuw_.d.mts","names":[],"sources":["../src/custom-app/function-context.ts"],"mappings":"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"}

package/dist/index.cjs

@@ -1,6 +1,6 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_react = require('./react-riTxd9ce.cjs');
+const require_react = require('./react-CkAQg9wB.cjs');
 let react = require("react");
 react = require_react.__toESM(react, 1);
 
@@ -388,14 +388,69 @@ function useSensitivity(measureId, opts = {}) {
 * Propagate hypothetical `(measure, delta)` changes upward through the
 * tree and return the estimated impact on every downstream measure — a
 * pure metric-tree walk, no warehouse query. Pass `null` to stay idle.
+*
+* Because it is database-free it can only use the coefficients it is GIVEN.
+* Without `opts.coefficients` from {@link useBaseline}, every driver edge
+* whose `.view.yml` declares no `coefficient:` contributes nothing and its
+* downstream measures are simply absent from `impacts` — no error, no
+* refusal. Without `opts.values`, multiplicative component edges come back
+* `unquantifiable` rather than sized.
 */
 function usePredict(changes, opts = {}) {
 	const { projectId, fetcher } = require_react.useOxyApp();
 	const enabled = opts.enabled !== false;
+	const { values, coefficients } = opts;
+	const body = {
+		changes,
+		...values ? { values } : {},
+		...coefficients?.length ? { coefficients } : {}
+	};
 	return useMetricTreeEndpoint(projectId && changes ? JSON.stringify({
 		projectId,
-		changes
-	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/predict`, { changes }, signal), enabled);
+		body
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/predict`, body, signal), enabled);
+}
+/**
+* Value a scenario's starting point, and measure the coefficients it needs.
+*
+* Two warehouse reads: the current value of every node reachable from
+* `request.roots`, and — for driver edges declaring no `coefficient:` — a fit
+* over the window. Both are expensive, which is why they live here and not in
+* {@link usePredict}: predict is database-free by design so it can re-run per
+* keystroke, and it CANNOT measure a coefficient itself.
+*
+* That is the whole reason to call this. Feed `data.values` and `data.fitted`
+* into `usePredict`; omit them and an undeclared edge propagates nothing.
+* Pass `null` to stay idle until levers and a period are chosen.
+*/
+function useBaseline(request, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && request ? JSON.stringify({
+		projectId,
+		request
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/baseline`, request, signal), enabled);
+}
+/**
+* Bucketed history for the levers and everything downstream, plus the forward
+* curve the forecaster expects next — the scenario's time axis.
+*
+* One warehouse query, so it belongs on a window change, not on a lever edit.
+* It returns the BASELINE curve only: the scenario's second curve is
+* arithmetic over this and a `usePredict` result — a proportional shift
+* landing `lag` buckets in — composed client-side precisely so editing a lever
+* costs no query.
+*
+* Treat a series with a `refusal` as a stated absence: it must not render as a
+* flat forward line. Pass `null` to stay idle.
+*/
+function useProjection(request, opts = {}) {
+	const { projectId, fetcher } = require_react.useOxyApp();
+	const enabled = opts.enabled !== false;
+	return useMetricTreeEndpoint(projectId && request ? JSON.stringify({
+		projectId,
+		request
+	}) : null, (signal) => postJson(fetcher, `${metricTreePath(projectId)}/projection`, request, signal), enabled);
 }
 /**
 * Period-over-period root-cause decomposition: recursively splits the
@@ -556,9 +611,9 @@ function useWorldModelGraph(opts = {}) {
 * to stay idle until an entity is chosen.
 */
 function useWorldModelInstances(entityId, opts = {}) {
-	const { projectId, fetcher } = require_react.useOxyApp();
+	const { projectId, appId, fetcher } = require_react.useOxyApp();
 	const enabled = opts.enabled !== false;
-	const { search, limit } = opts;
+	const { search, limit, scope } = opts;
 	const [data, setData] = react.useState(null);
 	const [loading, setLoading] = react.useState(enabled && !!projectId && !!entityId);
 	const [error, setError] = react.useState(null);
@@ -575,6 +630,10 @@ function useWorldModelInstances(entityId, opts = {}) {
 		const params = new URLSearchParams({ entity: entityId });
 		if (search) params.set("search", search);
 		if (limit != null) params.set("limit", String(limit));
+		if (scope) {
+			params.set("scope", scope);
+			if (appId) params.set("app", appId);
+		}
 		fetcher(`${worldModelPath(projectId)}/instances?${params}`, {
 			method: "GET",
 			signal: ctrl.signal
@@ -601,7 +660,9 @@ function useWorldModelInstances(entityId, opts = {}) {
 		entityId,
 		search,
 		limit,
-		fetcher
+		fetcher,
+		scope,
+		appId
 	]);
 	return {
 		data,
@@ -818,9 +879,10 @@ function useWorldModel() {
 //#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.
+* Client for the `/semantic/metric-tree*` endpoints. Surfaces the airlayer
+* metric-tree analyses — tree introspection, sensitivity, explain, opportunity
+* — plus the three legs of scenario forecasting (`baseline` levels,
+* `predict` propagation, `projection` curves) over typed methods.
 *
 * Construction is internal to {@link OxyClient} — call `client.metricTree`
 * to access an instance rather than building one yourself.
@@ -880,9 +942,50 @@ var MetricTreeClient = class {
 		return this.request(this.path(`/${encodeURIComponent(measureId)}/sensitivity${query}`));
 	}
 	/**
+	* Value a change's starting point, and measure the coefficients it needs.
+	*
+	* Two warehouse reads: the current value of every node reachable from
+	* `roots`, and — for driver edges that declare no `coefficient:` — a fit
+	* over the window. Both are expensive, which is why they live here and not
+	* in `predict`: `predict` is database-free by design so it can re-run per
+	* keystroke, and it CANNOT measure a coefficient itself.
+	*
+	* That is the whole reason to call this. Pass `fitted` back into `predict`
+	* and an undeclared edge propagates; omit it and `predict` has nothing to
+	* multiply by, so the impact is simply absent — no error, no refusal, just a
+	* downstream measure that never appears.
+	*
+	* @example
+	* ```typescript
+	* const baseline = await client.metricTree.getBaseline({
+	*   roots: ["marketing_spend.total_spend"],
+	*   time_dimension: "orders.order_date",
+	*   period: ["2025-09-01", "2025-09-30"],
+	* });
+	* const result = await client.metricTree.predict(
+	*   [{ measure: "marketing_spend.total_spend", delta: 10000 }],
+	*   { values: baseline.values, coefficients: baseline.fitted }
+	* );
+	* ```
+	*/
+	async getBaseline(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/baseline${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
+		});
+	}
+	/**
 	* Propagate hypothetical `(measure, delta)` changes upward through the
 	* tree. Returns the estimated impact on every downstream measure.
 	*
+	* Database-free, so it re-runs cheaply — and so it can only use
+	* coefficients it is GIVEN. Without `options.coefficients` from
+	* {@link getBaseline}, every edge whose `.view.yml` declares no
+	* `coefficient:` contributes nothing and its downstream measures are
+	* silently missing from `impacts`. Without `options.values`, multiplicative
+	* component edges come back `unquantifiable` rather than sized.
+	*
 	* @example
 	* ```typescript
 	* const result = await client.metricTree.predict([
@@ -890,11 +993,51 @@ var MetricTreeClient = class {
 	* ]);
 	* ```
 	*/
-	async predict(changes) {
+	async predict(changes, options = {}) {
 		const query = this.buildQuery();
 		return this.request(this.path(`/predict${query}`), {
 			method: "POST",
-			body: JSON.stringify({ changes })
+			body: JSON.stringify({
+				changes,
+				...options.values ? { values: options.values } : {},
+				...options.coefficients?.length ? { coefficients: options.coefficients } : {}
+			})
+		});
+	}
+	/**
+	* Draw the scenario's time axis: bucketed history for the levers and
+	* everything downstream, plus the forward curve the detector's own model
+	* expects next.
+	*
+	* The third leg of scenario forecasting. {@link getBaseline} gives levels
+	* and coefficients, {@link predict} propagates a change with no database at
+	* all, and this gives time — one warehouse query, so treat it like the
+	* baseline: fetch on a window change, not on a lever edit.
+	*
+	* **Returns the BASELINE curve only.** The scenario's second curve is
+	* arithmetic over this and a `predict` result — a proportional shift landing
+	* `lag` buckets in — and is composed client-side deliberately, so editing a
+	* lever costs no query.
+	*
+	* @example
+	* ```typescript
+	* const projection = await client.metricTree.getProjection({
+	*   roots: ["marketing_spend.total_spend"],
+	*   time_dimension: "orders.order_date",
+	*   period: ["2024-09-01", "2025-08-31"],
+	*   granularity: "day",
+	*   horizon: 30,
+	* });
+	* for (const series of projection.series) {
+	*   if (series.refusal) console.warn(series.measure, series.refusal);
+	* }
+	* ```
+	*/
+	async getProjection(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/projection${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
 		});
 	}
 	/**
@@ -943,6 +1086,66 @@ var MetricTreeClient = class {
 	}
 };
 
+//#endregion
+//#region src/peerCohort.ts
+/**
+* Client for the `/semantic/cohort` endpoint. Surfaces airlayer's peer-cohort
+* benchmarking — comparing an entity's subjects against their declared peers
+* on a measure, with exclusions explained rather than silently dropped.
+*
+* Construction is internal to {@link OxyClient} — call `client.peerCohort`
+* to access an instance rather than building one yourself.
+*
+* @example
+* ```typescript
+* const client = await OxyClient.create({ projectId: "...", apiKey: "..." });
+* const result = await client.peerCohort.resolve({
+*   entity: "restaurant_id",
+*   measure: "orders.net_revenue",
+*   time_dimension: "orders.order_date",
+*   period: ["2025-09-01", "2025-09-30"],
+* });
+* for (const excluded of result.excluded) {
+*   console.warn(excluded.key, excluded.reason);
+* }
+* ```
+*/
+var PeerCohortClient = class {
+	constructor(config, request) {
+		this.config = config;
+		this.request = request;
+	}
+	path(suffix) {
+		return `/${this.config.projectId}${suffix}`;
+	}
+	buildQuery(extra = {}) {
+		const params = { ...extra };
+		if (this.config.branch) params.branch = this.config.branch;
+		const qs = new URLSearchParams(params).toString();
+		return qs ? `?${qs}` : "";
+	}
+	/**
+	* Resolve a subject's peer cohort and every peer's comparison against it.
+	*
+	* @example
+	* ```typescript
+	* const result = await client.peerCohort.resolve({
+	*   entity: "restaurant_id",
+	*   measure: "orders.net_revenue",
+	*   time_dimension: "orders.order_date",
+	*   period: ["2025-09-01", "2025-09-30"],
+	* });
+	* ```
+	*/
+	async resolve(request) {
+		const query = this.buildQuery();
+		return this.request(this.path(`/semantic/cohort${query}`), {
+			method: "POST",
+			body: JSON.stringify(request)
+		});
+	}
+};
+
 //#endregion
 exports.AnomaliesClient = AnomaliesClient;
 exports.MetricTreeClient = MetricTreeClient;
@@ -950,6 +1153,7 @@ exports.OxyAnswer = require_react.OxyAnswer;
 exports.OxyApiError = require_react.OxyApiError;
 exports.OxyAppProvider = require_react.OxyAppProvider;
 exports.OxyChat = require_react.OxyChat;
+exports.PeerCohortClient = PeerCohortClient;
 exports.WorldModelScopeUnsupportedError = WorldModelScopeUnsupportedError;
 exports._resetCustomAppManifestCacheForTest = require_react._resetCustomAppManifestCacheForTest;
 exports.apiErrorFromResponse = require_react.apiErrorFromResponse;
@@ -964,6 +1168,7 @@ exports.readInjectedAppConfig = require_react.readInjectedAppConfig;
 exports.readJsonSseStream = readJsonSseStream;
 exports.setOxyAppLogger = require_react.setOxyAppLogger;
 exports.useAgentRun = require_react.useAgentRun;
+exports.useBaseline = useBaseline;
 exports.useDistribution = useDistribution;
 exports.useExplain = useExplain;
 exports.useFunction = require_react.useFunction;
@@ -973,6 +1178,7 @@ exports.useOpportunity = useOpportunity;
 exports.useOxyApp = require_react.useOxyApp;
 exports.usePredict = usePredict;
 exports.useProcedureRun = require_react.useProcedureRun;
+exports.useProjection = useProjection;
 exports.useQuery = require_react.useQuery;
 exports.useResolvedManifest = require_react.useResolvedManifest;
 exports.useSemanticQuery = require_react.useSemanticQuery;