@oxy-hq/sdk 2.5.0 → 2.8.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 
-import { A as UseSemanticQueryOpts, B as CustomerAppErrorReport, C as UseProcedureRunInput, D as UseQueryOpts, E as UseQueryInput, F as useProcedureRun, G as OxyAppFunctionManifest, H as apiErrorFromResponse, I as useQuery, J as _resetCustomerAppManifestCacheForTest, K as OxyAppManifest, L as useResolvedManifest, M as useAgentRun, N as useFunction, O as UseQueryResult, P as useOxyApp, R as useSemanticQuery, S as UseFunctionResult, T as UseProcedureRunResult, U as interpretCustomerAppError, V as OxyApiError, W as LoadManifestOptions, Y as loadCustomerAppManifest, _ as SemanticFilter, a as AppFetcher, b as UseAgentRunInput, c as OxyAppProvider, d as OxyChatProps, f as ProcedureProgress, g as SemanticDateRangeOp, h as SemanticArrayOp, i as AgentSqlArtifact, j as UseSemanticQueryResult, k as UseSemanticQueryInput, l as OxyAppProviderProps, m as ProcedureRunState, n as AgentRunEvent, o as OxyAnswer, p as ProcedureResult, q as ResolvedCustomerAppManifest, r as AgentRunState, s as OxyAnswerProps, t as AgentArtifact, u as OxyChat, v as SemanticScalarOp, w as UseProcedureRunOpts, x as UseAgentRunResult, y as SemanticTimeDimension, z as useTrackEvent } from "./react-BnpR8VRJ.mjs";
+import { A as UseSemanticQueryOpts, B as CustomAppErrorReport, C as UseProcedureRunInput, D as UseQueryOpts, E as UseQueryInput, F as useProcedureRun, G as OxyAppFunctionManifest, H as apiErrorFromResponse, I as useQuery, J as _resetCustomAppManifestCacheForTest, K as OxyAppManifest, L as useResolvedManifest, M as useAgentRun, N as useFunction, O as UseQueryResult, P as useOxyApp, R as useSemanticQuery, S as UseFunctionResult, T as UseProcedureRunResult, U as interpretCustomAppError, V as OxyApiError, W as LoadManifestOptions, Y as loadCustomAppManifest, _ as SemanticFilter, a as AppFetcher, b as UseAgentRunInput, c as OxyAppProvider, d as OxyChatProps, f as ProcedureProgress, g as SemanticDateRangeOp, h as SemanticArrayOp, i as AgentSqlArtifact, j as UseSemanticQueryResult, k as UseSemanticQueryInput, l as OxyAppProviderProps, m as ProcedureRunState, n as AgentRunEvent, o as OxyAnswer, p as ProcedureResult, q as ResolvedCustomAppManifest, r as AgentRunState, s as OxyAnswerProps, t as AgentArtifact, u as OxyChat, v as SemanticScalarOp, w as UseProcedureRunOpts, x as UseAgentRunResult, y as SemanticTimeDimension, z as useTrackEvent } from "./react-kHG5gkd-.mjs";
 //#region src/config.d.ts
 /**
  * Configuration for the Oxy SDK
@@ -141,15 +141,38 @@ interface ExplainNode {
   dimension_count?: number;
   children?: ExplainNode[];
 }
+/** Whether a driver's observed move pushes the target the way it actually
+ *  moved (`contributing`) or against it (`counteracting` — it offset part of
+ *  the move rather than causing it). `unknown` when no signed claim is
+ *  available: `direction: unknown` with no coefficient, or a flat
+ *  driver/target. */
+type DriverContribution = "contributing" | "counteracting" | "unknown";
+/** A driver's move split into the part its base forced and the part its own
+ *  ratio contributed. Emitted only when the driver genuinely tracks a sibling
+ *  rather than moving on its own — presence is the claim.
+ *  `base_driven_delta + ratio_driven_delta === driver_delta`. */
+interface PassthroughSplit {
+  base_measure: string;
+  ratio_previous: number;
+  ratio_current: number;
+  base_driven_delta: number;
+  ratio_driven_delta: number;
+}
 interface DriverAttribution {
   driver_measure: string;
   driver_previous: number;
   driver_current: number;
   driver_delta: number;
+  /** Both optional: an `explain_cache` row written before these fields shipped
+   *  is served verbatim, so absent means unclassified — not a default. */
+  direction?: DriverDirection;
+  contribution?: DriverContribution;
   coefficient?: number;
   form: DriverForm;
+  /** Absent for a purely qualitative driver (no coefficient). */
   estimated_target_impact?: number;
   description?: string;
+  passthrough?: PassthroughSplit;
 }
 type ExplainWarning = {
   type: "simpsons_paradox";
@@ -225,12 +248,31 @@ interface OpportunityResult {
   target: string;
   period: [string, string];
   overall_value: number;
-  /** "value_share" (additive) or "equal" (ratios). */
+  /**
+   * "rows" (rate-based additive sizing — the only basis that yields a sized
+   * upside figure), "value_share" (additive) or "equal" (ratios).
+   */
   weight_basis: string;
   dimensions: DimensionOpportunity[];
   skipped_dimensions: SkippedDimension[];
   downstream: PredictImpact[];
 }
+/**
+ * Single-period structural decomposition. The server auto-derives the
+ * baseline as the equal-length window immediately before `period`, then
+ * returns an {@link ExplainResult}-shaped payload (so the same renderers
+ * work). Ignore the delta fields when rendering a pure distribution.
+ */
+interface DistributionRequest {
+  target: string;
+  time_dimension: string;
+  /** `[start, end]` inclusive date strings. */
+  period: [string, string];
+}
+interface TimeDimensionsResponse {
+  /** view name → fully-qualified time-dimension ids (`view.dim`). */
+  by_view: Record<string, string[]>;
+}
 /**
  * Shape of the inner request helper exposed by `OxyClient`. The metric-tree
  * client reuses it to inherit auth headers, timeout, baseUrl, and project
@@ -334,6 +376,13 @@ declare class MetricTreeClient {
 //#region src/anomalies.d.ts
 type AnomalyStatus = "new" | "acknowledged" | "dismissed";
 type AnomalySeverity = "low" | "medium" | "high";
+/** One filter pinning an anomaly (or a failed monitor) to a segment. */
+interface AnomalyFilter {
+  /** Fully-qualified dimension id, e.g. `"sales_daily.restaurant_id"`. */
+  member: string;
+  /** Matched values (OR within a filter). */
+  values: string[];
+}
 /**
  * One row in the anomaly inbox. Detected by `oxy-metric-monitoring` per
  * `.monitor.yml` entry; upserted by repeat scans so unresolved anomalies
@@ -355,6 +404,18 @@ interface Anomaly {
   severity: AnomalySeverity | string;
   status: AnomalyStatus | string;
   label?: string | null;
+  /**
+   * Stable key derived from the monitor's filters (e.g.
+   * `"sales_daily.restaurant_id=loc-abc"`). Empty for chain-wide monitors.
+   */
+  dimension_key: string;
+  /**
+   * Raw filters identifying the segment; `null` for chain-wide monitors.
+   * Always present on the wire (the server serializes it unconditionally),
+   * hence required-nullable rather than optional — same shape as
+   * {@link ScanFailure.filters}.
+   */
+  filters: AnomalyFilter[] | null;
   /** Cached ExplainResult — populated by `POST /anomalies/:id/explain`. */
   explain_cache?: ExplainResult | null;
   explain_cached_at?: string | null;
@@ -373,10 +434,38 @@ interface ScanOptions {
   /** Override the reference "now" date (YYYY-MM-DD) — useful for demos. */
   as_of?: string;
 }
+/** One `.monitor.yml` entry that errored during a scan. */
+interface ScanFailure {
+  measure: string;
+  time_dimension: string;
+  granularity: string;
+  label: string | null;
+  /** Segment key for a `group_by`/filtered monitor; empty for chain-wide. */
+  dimension_key: string;
+  /** Raw filters identifying the segment; null for chain-wide monitors. */
+  filters: AnomalyFilter[] | null;
+  error: string;
+}
 interface ScanResponse {
   monitors_scanned: number;
   monitors_failed: number;
   anomalies_persisted: number;
+  /**
+   * True when the scan is still running server-side (it exceeded the 55 s
+   * synchronous window, or a scan started within the last 60 s and this call
+   * was debounced). The counts are all `0` in that case — they are NOT a
+   * "nothing found" result. Refetch with `list()` after a short delay.
+   */
+  pending: boolean;
+  /**
+   * Per-monitor failures. Empty array (never absent) on a clean scan and on
+   * the `pending` path, where failures aren't known yet.
+   */
+  failures: ScanFailure[];
+}
+interface ExplainOptions {
+  /** Recompute even when the row already has a cached result. */
+  refresh?: boolean;
 }
 type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;
 /**
@@ -413,11 +502,20 @@ declare class AnomaliesClient {
    * workspace, runs the detector, and upserts matching rows into the
    * inbox. Returns counts of scanned / failed / persisted.
    *
+   * Long-running: the server waits up to 55 s, then returns
+   * `pending: true` with zeroed counts while the scan finishes in the
+   * background. Always check `pending` before treating `0` as "nothing
+   * found", and refetch with {@link list} shortly after.
+   *
    * @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`);
+   * if (result.pending) {
+   *   console.log("scan still running — refetch shortly");
+   * } else {
+   *   console.log(`${result.anomalies_persisted} anomalies detected`);
+   * }
    * ```
    */
   scan(options?: ScanOptions): Promise<ScanResponse>;
@@ -427,16 +525,48 @@ declare class AnomaliesClient {
   updateStatus(anomalyId: string, status: AnomalyStatus): Promise<Anomaly>;
   /**
    * Run the metric-tree `explain` for an anomaly and cache the result on
-   * the row. Subsequent calls return the cached `ExplainResult` instantly.
+   * the row. Subsequent calls return the cached `ExplainResult` instantly;
+   * pass `{ refresh: true }` to bust the cache and recompute.
+   *
+   * The uncached path runs a 20-30 s recursive driver search — budget for it
+   * (or read `explain_cache` off the row from {@link list} when it's already
+   * populated).
    */
-  explain(anomalyId: string): Promise<ExplainResult>;
+  explain(anomalyId: string, options?: ExplainOptions): Promise<ExplainResult>;
 }
 //#endregion
-//#region src/customer-app/debug.d.ts
+//#region src/custom-app/base64.d.ts
+/**
+ * Encode bytes as standard (padded) base64.
+ *
+ * ```ts
+ * const pdf = new Uint8Array(await renderReport());
+ * await ctx.email.send({
+ *   to: ctx.user.email,
+ *   subject: "Report",
+ *   text: "attached",
+ *   attachments: [{ filename: "report.pdf", content: bytesToBase64(pdf) }]
+ * });
+ * ```
+ *
+ * For **text** you generated, skip this entirely and pass the string with
+ * `encoding: "utf8"` — it needs no encoder and stays byte-exact for non-ASCII.
+ */
+declare function bytesToBase64(input: Uint8Array | ArrayBuffer | ArrayBufferView): string;
+/**
+ * Decode standard base64 to bytes — e.g. the body from
+ * `ctx.storage.get(key, { encoding: "base64" })`.
+ *
+ * Throws on malformed input rather than returning a short buffer: a truncated
+ * decode that reports success is a corrupt file nobody notices.
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+//#endregion
+//#region src/custom-app/debug.d.ts
 /** Untyped at the boundary — keep it loose so server-side schema
  * additions don't break older bundles. Stable enough for inspection
  * but not a contract clients should depend on field-by-field. */
-interface CustomerAppDebugSnapshot {
+interface CustomAppDebugSnapshot {
   org_slug: string;
   app_slug: string;
   app: {
@@ -460,13 +590,13 @@ interface CustomerAppDebugSnapshot {
 }
 /**
  * Fetch the server-side diagnostic snapshot for this bundle. Pair with
- * `loadCustomerAppManifest()` — pass its result here. Logs the
+ * `loadCustomAppManifest()` — pass its result here. Logs the
  * snapshot through the SDK logger so it appears in the bundle's
  * console at info level.
  */
-declare function getCustomerAppDebug(resolved: ResolvedCustomerAppManifest): Promise<CustomerAppDebugSnapshot>;
+declare function getCustomAppDebug(resolved: ResolvedCustomAppManifest): Promise<CustomAppDebugSnapshot>;
 //#endregion
-//#region src/customer-app/function-context.d.ts
+//#region src/custom-app/function-context.d.ts
 /**
  * The request passed as the first argument to a function's default export.
  *
@@ -486,12 +616,46 @@ interface OxyFunctionUser {
   id: string;
   email: string;
   orgId: string;
+  /**
+   * The caller's role **within this app**, derived server-side from app
+   * membership (with org-owner / Oxy-staff break-glass). Absent when they hold
+   * no membership.
+   *
+   * This is the value to gate a privileged surface on — it cannot be forged by
+   * the client, unlike a query param or a client-side flag:
+   *
+   * ```ts
+   * if (ctx.user.appRole !== "admin") {
+   *   return Response.json({ error: "forbidden" }, { status: 403 });
+   * }
+   * ```
+   *
+   * Note it is deliberately NOT the org role: an app admin administers one app
+   * without holding org-Admin (which also carries billing and member management).
+   */
+  appRole?: "admin" | "member";
 }
 /** Result of a `ctx.fetch` call. */
 interface OxyFetchResult {
   status: number;
+  /** Response body, decoded per the requested {@link OxyFetchInit.encoding}. */
   body: string;
+  /** Echoes how `body` was encoded (`"utf8"` unless base64 was requested). */
+  encoding?: "utf8" | "base64";
 }
+/**
+ * `init` for `ctx.fetch` — the standard `RequestInit` fields the host honours
+ * (`method`, `headers`, `body`) plus how to decode the response.
+ */
+type OxyFetchInit = RequestInit & {
+  /**
+   * How to decode the response body. `"utf8"` (default) is **lossy for
+   * binary** — every non-UTF-8 byte becomes U+FFFD, so a fetched PDF/PNG comes
+   * back corrupt. Pass `"base64"` for any binary response, e.g. to hand it
+   * straight to an email attachment.
+   */
+  encoding?: "utf8" | "base64";
+};
 /** `ctx.warehouse.*` — writes to one of the app's configured destination databases. */
 interface OxyWarehouseApi {
   insert(database: string, table: string, rows: OxyFunctionRow[]): Promise<unknown>;
@@ -539,6 +703,43 @@ interface EmailSendInput {
    * background (retried) sends become exactly-once once it does.
    */
   idempotencyKey?: string;
+  /**
+   * Files to attach. Max 20 per send, and **10 MiB decoded in total** — SES
+   * caps a whole message near 40 MB, so for anything larger store the file with
+   * {@link OxyStorageApi} and email a presigned link instead of inlining it.
+   *
+   * `content` is base64 by default; for generated text set
+   * `encoding: "utf8"` and attach the string as-is.
+   */
+  attachments?: EmailAttachment[];
+}
+/** One attachment on {@link EmailSendInput}. */
+interface EmailAttachment {
+  /** Filename shown to the recipient. Required; path separators are stripped. */
+  filename: string;
+  /**
+   * File contents, interpreted per {@link EmailAttachment.encoding} — base64 by
+   * default, which is the only way binary crosses the isolate boundary.
+   */
+  content: string;
+  /**
+   * How `content` is encoded. Defaults to `"base64"`.
+   *
+   * Use `"utf8"` to attach text the function just generated (CSV, JSON, HTML)
+   * — it needs no encoder and is byte-exact for non-ASCII. `btoa` is the wrong
+   * tool there: it encodes U+0080..U+00FF as *Latin1*, so accented text comes
+   * out as mojibake rather than as an error. For binary, take base64 straight
+   * from the source — `ctx.storage.get(key, { encoding: "base64" })` or
+   * `ctx.fetch(url, { encoding: "base64" })` — or {@link bytesToBase64} for a
+   * `Uint8Array` you built yourself.
+   */
+  encoding?: "base64" | "utf8";
+  /** MIME type; defaults to `application/octet-stream`. */
+  contentType?: string;
+  /** Render inline (e.g. an image referenced as `cid:<contentId>`) instead of as a download. */
+  inline?: boolean;
+  /** Content-ID for an inline part, referenced from the HTML body as `cid:<contentId>`. */
+  contentId?: string;
 }
 /** Result of a successful `ctx.email.send`. */
 interface EmailSendResult {
@@ -549,6 +750,164 @@ interface EmailSendResult {
 interface OxyEmailApi {
   send(input: EmailSendInput): Promise<EmailSendResult>;
 }
+/** Input to `ctx.storage.getUploadUrl`. */
+interface StorageUploadUrlInput {
+  /**
+   * Destination path inside the app's silo, e.g. `"uploads/q1-report.pdf"`.
+   * Segments are sanitized server-side and cannot escape the silo. Omit to use
+   * `filename`, which is placed under `uploads/`.
+   */
+  pathname?: string;
+  /** Shorthand for `pathname: "uploads/<filename>"`. */
+  filename?: string;
+  /** MIME type; bound into the presigned PUT signature. Inferred when omitted. */
+  contentType?: string;
+  /**
+   * Exact byte length of the upload, bound into the signature — S3 rejects a
+   * body of any other size. Capped by the server's upload ceiling (100 MiB by
+   * default).
+   */
+  contentLength: number;
+  /** Presign lifetime in seconds (default 900; max 604800 — SigV4's own limit). */
+  expiresInSeconds?: number;
+}
+/** A minted presigned upload. */
+interface StorageUploadUrl {
+  /** Presigned PUT — the browser uploads the file bytes directly to this URL. */
+  url: string;
+  /**
+   * The stored key. Record it (e.g. on a row in your warehouse) — it is how you
+   * fetch, list or link to the asset later. A random suffix is added so two
+   * people uploading `report.pdf` don't collide.
+   */
+  key: string;
+  /** ISO-8601 expiry of the presigned URL. */
+  expiresAt: string;
+}
+/** A minted presigned download. */
+interface StorageDownloadUrl {
+  url: string;
+  expiresAt: string;
+}
+/** One asset in the app's silo. */
+interface StorageObject {
+  key: string;
+  size: number;
+  contentType?: string | null;
+  /** ISO-8601. */
+  lastModified?: string | null;
+}
+/** One page of {@link OxyStorageApi.list}. */
+interface StorageListPage {
+  objects: StorageObject[];
+  /** Pass back as `cursor` to fetch the next page; `null` when complete. */
+  cursor: string | null;
+  hasMore: boolean;
+}
+/** Options for {@link OxyStorageApi.put}. */
+interface StoragePutOptions {
+  /** MIME type. Inferred from the pathname's extension when omitted. */
+  contentType?: string;
+  /**
+   * How `body` is encoded. `"base64"` is what makes **binary** generated assets
+   * (PDF, PNG, Parquet) possible — a UTF-8 string would corrupt them.
+   */
+  encoding?: "utf8" | "base64";
+  /** Append a short random component before the extension to avoid collisions. */
+  addRandomSuffix?: boolean;
+  /**
+   * Replace an existing asset at this path. Defaults to `false` — writing over
+   * an asset by accident is worse than an error, so this is opt-in.
+   */
+  allowOverwrite?: boolean;
+  /** `Cache-Control: max-age=<seconds>` stored on the object. */
+  cacheControlMaxAge?: number;
+}
+/** Result of a `put` (and of `copy`). */
+interface StoragePutResult {
+  key: string;
+  size: number;
+  contentType: string;
+}
+/**
+ * `ctx.storage` — this app's **asset store**, covering both kinds of file an app
+ * produces, in one silo (`customer-app-storage/<app_id>/`):
+ *
+ * - **Uploaded** — a human picks a file; `getUploadUrl` mints a presigned PUT and
+ *   the browser uploads **straight to S3**, so uploads aren't bounded by the
+ *   request-body limit and the bytes never pass through your function.
+ * - **Generated** — your function produces the file (a rendered PDF, a CSV
+ *   export, a chart PNG) and writes it with `put`, using
+ *   `{ encoding: "base64" }` for binary.
+ *
+ * Gated by the fail-closed `storage.read` / `storage.write` capabilities in
+ * `oxy-app.json`. Every asset is private; reads are always presigned and
+ * time-boxed. Keys are confined to your app — another app's key is rejected.
+ *
+ * ```ts
+ * // Uploaded: mint a URL, browser PUTs to it, then record `key`.
+ * const { url, key } = await ctx.storage.getUploadUrl({
+ *   filename: "q1-report.pdf", contentType: "application/pdf", contentLength: size,
+ * });
+ *
+ * // Generated: write a CSV your function just built.
+ * const { key } = await ctx.storage.put("generated/jan.csv", csv);
+ *
+ * // Either way: email a link that outlives the request.
+ * const { url: link } = await ctx.storage.getDownloadUrl(key, {
+ *   expiresInSeconds: 604800, download: true,
+ * });
+ * ```
+ */
+interface OxyStorageApi {
+  /** Mint a presigned PUT for a browser upload (requires `storage.write`). */
+  getUploadUrl(input: StorageUploadUrlInput): Promise<StorageUploadUrl>;
+  /**
+   * Mint a presigned GET (requires `storage.read`). `download: true` forces a
+   * save-as via `Content-Disposition`, which is what an emailed link wants.
+   */
+  getDownloadUrl(key: string, opts?: {
+    expiresInSeconds?: number;
+    download?: boolean;
+  }): Promise<StorageDownloadUrl>;
+  /**
+   * Write a generated asset (requires `storage.write`). Capped at 6 MiB — for
+   * anything larger, mint a presigned upload URL and stream to it.
+   */
+  put(pathname: string, body: string, opts?: StoragePutOptions): Promise<StoragePutResult>;
+  /** Read an asset back; `null` when absent (requires `storage.read`). */
+  get(key: string, opts?: {
+    encoding?: "utf8" | "base64";
+  }): Promise<{
+    body: string;
+    contentType: string | null;
+    size: number;
+    encoding: string;
+  } | null>;
+  /** Metadata without the body; `null` when absent (requires `storage.read`). */
+  head(key: string): Promise<StorageObject | null>;
+  /**
+   * One page of assets (requires `storage.read`). Paginated deliberately — pass
+   * the returned `cursor` back to walk a large silo without loading it all.
+   */
+  list(opts?: {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<StorageListPage>;
+  /**
+   * Delete one or many assets (requires `storage.write`). Idempotent — deleting
+   * an absent key is a no-op success. `deleted` is the number of keys **accepted**
+   * for deletion (an absent key counts too), not a count of keys that existed.
+   */
+  delete(keyOrKeys: string | string[]): Promise<{
+    deleted: number;
+  }>;
+  /** Server-side copy within the app's silo (requires `storage.write`). */
+  copy(fromKey: string, toPathname: string, opts?: {
+    allowOverwrite?: boolean;
+  }): Promise<StoragePutResult>;
+}
 /**
  * The data-plane context passed as the second argument to a function's default
  * export. Mirrors the host-assembled `ctx` (`__buildCtx` in `runtime.rs`);
@@ -567,21 +926,26 @@ interface OxyFunctionContext {
   queryStream(sql: string, opts?: {
     batchSize?: number;
   }): AsyncGenerator<OxyFunctionRow[], void, unknown>;
-  /** SSRF-allowlisted outbound HTTP with a response-size cap. */
-  fetch(url: string, init?: RequestInit): Promise<OxyFetchResult>;
+  /**
+   * SSRF-allowlisted outbound HTTP with a response-size cap. Pass
+   * `{ encoding: "base64" }` for a binary response — the default UTF-8 decode
+   * corrupts it.
+   */
+  fetch(url: string, init?: OxyFetchInit): Promise<OxyFetchResult>;
   warehouse: OxyWarehouseApi;
   secrets: OxySecretsApi;
   semantic: OxySemanticApi;
   airway: OxyAirwayApi;
   email: OxyEmailApi;
+  storage: OxyStorageApi;
 }
 /** Signature of a function's default export: `export default async (req, ctx) => Response`. */
 type OxyFunctionHandler = (req: OxyFunctionRequest, ctx: OxyFunctionContext) => Promise<Response> | Response;
 //#endregion
-//#region src/customer-app/inject.d.ts
+//#region src/custom-app/inject.d.ts
 /**
  * Shape of `window.__OXY_APP__` written by oxy at serve time.
- * Consumed by `loadCustomerAppManifest` as the authoritative identity
+ * Consumed by `loadCustomAppManifest` as the authoritative identity
  * source (overrides any hints in `oxy-app.json`).
  */
 interface OxyInjectedAppConfig {
@@ -607,7 +971,7 @@ declare global {
  */
 declare function readInjectedAppConfig(): OxyInjectedAppConfig | undefined;
 //#endregion
-//#region src/customer-app/logger.d.ts
+//#region src/custom-app/logger.d.ts
 type OxyAppLogLevel = "debug" | "info" | "warn" | "error";
 interface OxyAppLogger {
   log(level: OxyAppLogLevel, msg: string, ctx?: Record<string, unknown>): void;
@@ -617,5 +981,333 @@ declare function setOxyAppLogger(logger: OxyAppLogger | null): void;
 /** Used by the SDK internals; not part of the public surface. */
 declare function getOxyAppLogger(): OxyAppLogger;
 //#endregion
-export { type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, AnomaliesClient, type Anomaly, type AnomalySeverity, type AnomalyStatus, type AppFetcher, type CustomerAppDebugSnapshot, type CustomerAppErrorReport, type DimensionOpportunity, type DriverAttribution, type DriverConfidence, type DriverDirection, type DriverForm, type DriverStrength, type EdgeKind, type EmailSendInput, type EmailSendResult, type ExplainConfigOverride, type ExplainNode, type ExplainRequest, type ExplainResult, type ExplainSibling, type ExplainWarning, type ListAnomaliesOptions, type ListAnomaliesResponse, type LoadManifestOptions, type MetricEdge, type MetricNode, type MetricTree, MetricTreeClient, type OpportunityRequest, type OpportunityResult, type OxyAirwayApi, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppFunctionManifest, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyEmailApi, type OxyFetchResult, type OxyFunctionContext, type OxyFunctionHandler, type OxyFunctionRequest, type OxyFunctionRow, type OxyFunctionUser, type OxyInjectedAppConfig, type OxySecretsApi, type OxySemanticApi, type OxyWarehouseApi, type PredictChange, type PredictImpact, type PredictResult, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ResolvedCustomerAppManifest, type ScanOptions, type ScanResponse, type SegmentOpportunity, type SemanticArrayOp, type SemanticDateRangeOp, type SemanticFilter, type SemanticScalarOp, type SemanticTimeDimension, type SensitivityDriver, type SensitivityResult, type SkippedDimension, type SplitKind, type UseAgentRunInput, type UseAgentRunResult, type UseFunctionResult, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, _resetCustomerAppManifestCacheForTest, apiErrorFromResponse, getCustomerAppDebug, getOxyAppLogger, interpretCustomerAppError, loadCustomerAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useFunction, useOxyApp, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
+//#region src/custom-app/metric-tree-hooks.d.ts
+/** Shared result envelope for every metric-tree hook. */
+interface MetricTreeHookResult<Data> {
+  data: Data | null;
+  loading: boolean;
+  error: Error | null;
+  /** Force a re-run, bypassing nothing — the server honors `?refresh`. */
+  refetch: () => void;
+}
+interface EndpointOpts {
+  /** Set false to skip the request (e.g. waiting on a user selection). */
+  enabled?: boolean;
+}
+interface UseMetricTreeOpts extends EndpointOpts {
+  /** Optional measure id to root the returned subtree at. */
+  root?: string;
+}
+/**
+ * The project's metric tree — measures (nodes) and their component /
+ * driver relationships (edges) — or the subtree rooted at `opts.root`.
+ * The structural backbone every other metric-tree analysis reads against.
+ */
+declare function useMetricTree(opts?: UseMetricTreeOpts): MetricTreeHookResult<MetricTree>;
+/**
+ * Ranked drivers of `measureId`, by influence — the "what moves this
+ * measure" question. Pass `null` to stay idle until a measure is chosen.
+ */
+declare function useSensitivity(measureId: string | null, opts?: EndpointOpts): MetricTreeHookResult<SensitivityResult>;
+/**
+ * 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.
+ */
+declare function usePredict(changes: PredictChange[] | null, opts?: EndpointOpts): MetricTreeHookResult<PredictResult>;
+/**
+ * Period-over-period root-cause decomposition: recursively splits the
+ * target measure by components and dimensions until the move concentrates.
+ * This is the heavy one — it can fire many warehouse queries and the
+ * server caps it at 45s. Pass `null` to defer until periods are chosen.
+ */
+declare function useExplain(request: ExplainRequest | null, opts?: EndpointOpts): MetricTreeHookResult<ExplainResult>;
+/**
+ * Single-period distribution of a measure — an {@link ExplainResult}
+ * against an auto-derived immediately-prior baseline. Same renderers as
+ * `useExplain`; ignore the delta fields for a pure distribution view.
+ */
+declare function useDistribution(request: DistributionRequest | null, opts?: EndpointOpts): MetricTreeHookResult<ExplainResult>;
+/**
+ * Segment opportunity sizing for a measure over a period: finds
+ * underperforming segments and sizes the addressable upside of closing
+ * each rate gap against a benchmark peer. Pass `null` to stay idle until
+ * a target + period are chosen.
+ */
+declare function useOpportunity(request: OpportunityRequest | null, opts?: EndpointOpts): MetricTreeHookResult<OpportunityResult>;
+/**
+ * The queryable time dimensions per view (`view.dim` ids) — what a
+ * bundle offers as the period axis for `explain` / `opportunity` /
+ * `distribution` instead of hardcoding a curated map.
+ */
+declare function useTimeDimensions(opts?: EndpointOpts): MetricTreeHookResult<TimeDimensionsResponse>;
+//#endregion
+//#region src/custom-app/sse.d.ts
+/**
+ * Read a `text/event-stream` response, invoking `onEvent` with each parsed
+ * JSON frame. Frames that fail to parse are skipped (a malformed frame must
+ * not tear down the whole stream). Resolves when the body closes.
+ */
+declare function readJsonSseStream<E>(resp: Response, onEvent: (event: E) => void): Promise<void>;
+//#endregion
+//#region src/worldModel.d.ts
+/** How a measure aggregates across the entity hierarchy. */
+type AdditivityClass = "additive" | "non_additive" | "passthrough";
+interface WorldModelMeasure {
+  name: string;
+  measure_type: string;
+  additivity: AdditivityClass;
+  description?: string | null;
+  expr?: string | null;
+  label?: string | null;
+  /** True when the measure decomposes into a metric-tree driver breakdown. */
+  has_breakdown?: boolean;
+}
+/** A measure promoted onto this entity from a descendant view. */
+interface WorldModelInducedMeasure extends WorldModelMeasure {
+  /** View the measure is actually declared on. */
+  promoted_from: string;
+  /** Promotion path from the declaring view up to this entity. */
+  path: string[];
+}
+interface WorldModelDimension {
+  name: string;
+  dim_type: string;
+  description?: string | null;
+  label?: string | null;
+}
+interface WorldModelEntity {
+  id: string;
+  label: string;
+  view: string;
+  description?: string | null;
+  depth: number;
+  dimensions: WorldModelDimension[];
+  own_measures: WorldModelMeasure[];
+  induced_measures: WorldModelInducedMeasure[];
+  display_field?: string | null;
+}
+/** A promotion edge: measures on `from` promote up to `to`. */
+interface WorldModelEdge {
+  from: string;
+  to: string;
+  functional: boolean;
+}
+interface WorldModel {
+  entities: WorldModelEntity[];
+  edges: WorldModelEdge[];
+}
+interface WmInstance {
+  key: string;
+  display: string;
+}
+interface WmInstancesResponse {
+  total: number;
+  has_more: boolean;
+  items: WmInstance[];
+}
+interface WmEntityCount {
+  matched: number;
+  total: number;
+  /** Sample of reachable descendant rows at this grain (display strings). */
+  sample?: string[];
+  /** Navigation keys aligned with `sample`. */
+  sample_keys?: string[];
+}
+interface WmFilterCountsResponse {
+  counts: Record<string, WmEntityCount>;
+}
+interface WmBreakdownNode {
+  /** Metric node id `view.measure`. */
+  id: string;
+  view: string;
+  measure: string;
+  label: string;
+  measure_type: string;
+  is_composite: boolean;
+  is_root: boolean;
+  expr?: string | null;
+  /** Filled by `value` frames; null while pending. */
+  value: string | null;
+  unvalued_reason: string | null;
+}
+interface WmBreakdownEdge {
+  from: string;
+  to: string;
+  operator: "add" | "sub" | "mul" | "div";
+  sign: number;
+}
+/** One frame of the measure-breakdown stream. The `init` frame carries the
+ *  graph shape; `value` frames fill node values in as they resolve. */
+type WmMeasureBreakdownEvent = {
+  kind: "init";
+  root: string;
+  nodes: Omit<WmBreakdownNode, "value" | "unvalued_reason">[];
+  edges: WmBreakdownEdge[];
+} | {
+  kind: "value";
+  node_id: string;
+  value: string | null;
+  unvalued_reason: string | null;
+} | {
+  kind: "done";
+};
+/** Accumulated breakdown — the shape `useMeasureBreakdown` folds the
+ *  stream into. */
+interface WmMeasureBreakdown {
+  root: string;
+  nodes: WmBreakdownNode[];
+  edges: WmBreakdownEdge[];
+}
+//#endregion
+//#region src/custom-app/world-model-hooks.d.ts
+interface UseWorldModelGraphResult {
+  data: WorldModel | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+/**
+ * The world-model graph — entities (nodes), their measures/dimensions, and
+ * how measures promote across the entity hierarchy (edges). Applies the
+ * project's `.world-model.yml` display config server-side.
+ *
+ * @remarks
+ * This returns the raw semantic-layer entity graph. For the higher-level
+ * node-paradigm interface (`world.metric(id)` speaking `expand` / `explain` /
+ * `size`), use {@link useWorldModel} from `./world-node` instead.
+ */
+declare function useWorldModelGraph(opts?: {
+  enabled?: boolean;
+}): UseWorldModelGraphResult;
+interface UseWorldModelInstancesOpts {
+  /** Substring/prefix search over the entity's display field. */
+  search?: string;
+  /** Max rows to return (default 50 server-side). */
+  limit?: number;
+  enabled?: boolean;
+}
+interface UseWorldModelInstancesResult {
+  data: WmInstancesResponse | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+/**
+ * List the instances (rows) of `entityId` — a bounded, searchable picker
+ * over the entity's primary keys + display label. Pass `null` for `entityId`
+ * to stay idle until an entity is chosen.
+ */
+declare function useWorldModelInstances(entityId: string | null, opts?: UseWorldModelInstancesOpts): UseWorldModelInstancesResult;
+interface UseMeasureBreakdownResult {
+  /** Accumulated breakdown graph; null until the `init` frame. */
+  breakdown: WmMeasureBreakdown | null;
+  loading: boolean;
+  done: boolean;
+  error: Error | null;
+}
+/**
+ * Stream the driver-tree breakdown of one instance's measure — the metric
+ * decomposition (add/sub/mul/div component graph) with each node's value
+ * filling in as it resolves. This is the per-instance RCA view. Pass `null`
+ * for `measure` to stay idle.
+ */
+declare function useMeasureBreakdown(entityId: string | null, keyValue: string | null, measure: string | null): UseMeasureBreakdownResult;
+//#endregion
+//#region src/custom-app/world-node.d.ts
+/** A `dimension → value` scope narrowed onto a node via {@link MetricHandle.drill}. */
+type MetricScope = Readonly<Record<string, string>>;
+/** Options for {@link MetricHandle.explain} — an {@link ExplainRequest} minus
+ *  the `target`, which the handle supplies from its own id. */
+type ExplainOpts = Omit<ExplainRequest, "target">;
+/** Options for {@link MetricHandle.size} — an {@link OpportunityRequest} minus
+ *  the `target`. */
+type SizeOpts = Omit<OpportunityRequest, "target">;
+/** One child revealed by {@link MetricHandle.expand}: the child measure's
+ *  node, the edge that connects it to the parent, and a handle to recurse. */
+interface ExpandedNode {
+  /** The child measure (a component or a driver of the parent). */
+  node: MetricNode;
+  /** The parent → child edge — `kind`, `direction`, `strength`, `form`, … */
+  edge: MetricEdge;
+  /** A live handle on the child, carrying the parent's scope. */
+  handle: MetricHandle;
+}
+/**
+ * A live handle on one metric node. Carry it around and call a verb; every
+ * verb returns either more nodes (`expand`), a scoped handle (`drill`), or an
+ * analysis result (`explain` / `size` / `drivers`).
+ */
+interface MetricHandle {
+  /** Fully-qualified measure id (`view.measure`). */
+  readonly id: string;
+  /** The scope narrowed onto this handle by `drill` (empty for a root handle). */
+  readonly scope: MetricScope;
+  /** The measure's own tree node (label, expr, is_composite). */
+  node(signal?: AbortSignal): Promise<MetricNode>;
+  /** One hop of relationships — the metric's components and drivers as child nodes. */
+  expand(signal?: AbortSignal): Promise<ExpandedNode[]>;
+  /** The declared drivers of this measure, ranked by influence (sensitivity). */
+  drivers(signal?: AbortSignal): Promise<SensitivityResult>;
+  /** Root-cause a period-over-period move: why it dropped or climbed. */
+  explain(opts: ExplainOpts, signal?: AbortSignal): Promise<ExplainResult>;
+  /** Compare this node to its peers across each dimension and size the gap. */
+  size(opts: SizeOpts, signal?: AbortSignal): Promise<OpportunityResult>;
+  /** Narrow into a segment or entity instance — returns a scoped handle. */
+  drill(scope: Record<string, string>): MetricHandle;
+}
+/**
+ * The World Model interface, scoped to one project. The whole surface hangs
+ * off this: grab a {@link MetricHandle} with `metric(id)` and the handle
+ * speaks the verbs, or pull the whole graph with `tree(root?)`.
+ */
+interface WorldModelApi {
+  /** The active project id, or `null` before `<OxyAppProvider>` resolves one. */
+  readonly projectId: string | null;
+  /** The metric tree, rooted anywhere you like (default: the whole tree). */
+  tree(root?: string, signal?: AbortSignal): Promise<MetricTree>;
+  /** A live handle on one measure node. */
+  metric(id: string): MetricHandle;
+}
+/**
+ * Thrown by the value verbs (`explain` / `size`) when called on a handle that
+ * has been `drill`ed. The metric-tree backend cannot yet scope these analyses
+ * to a segment, so failing loud beats returning population numbers for a
+ * question that asked about one segment.
+ */
+declare class WorldModelScopeUnsupportedError extends Error {
+  readonly code = "world_model_scope_unsupported";
+  readonly scope: MetricScope;
+  constructor(verb: string, scope: MetricScope);
+}
+/**
+ * Build a {@link WorldModelApi} over a project id and fetcher. Framework-
+ * agnostic — `useWorldModel()` wraps this for React, but it is directly
+ * unit-testable with a mock fetcher.
+ */
+declare function createWorldModel(projectId: string | null, fetcher: AppFetcher): WorldModelApi;
+/**
+ * The World Model node interface, scoped to the active `<OxyAppProvider>`
+ * project. Returns a stable {@link WorldModelApi} — grab a node with
+ * `world.metric(id)` and let it speak the verbs.
+ *
+ * @example
+ * ```tsx
+ * const world = useWorldModel();
+ * const revenue = world.metric("orders.net_revenue");
+ * const children = await revenue.expand();       // components + drivers
+ * const rca = await revenue.explain({
+ *   time_dimension: "orders.order_date",
+ *   current_period: ["2026-06-01", "2026-06-30"],
+ *   previous_period: ["2026-05-01", "2026-05-31"],
+ * });
+ * ```
+ *
+ * @remarks
+ * This is the node-paradigm hook. For the raw semantic-layer entity/measure
+ * graph, use {@link useWorldModelGraph} instead.
+ */
+declare function useWorldModel(): WorldModelApi;
+//#endregion
+export { type AdditivityClass, type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, AnomaliesClient, type Anomaly, type AnomalyFilter, type AnomalySeverity, type AnomalyStatus, type AppFetcher, type CustomAppDebugSnapshot, type CustomAppErrorReport, type DimensionOpportunity, type DistributionRequest, type DriverAttribution, type DriverConfidence, type DriverDirection, type DriverForm, type DriverStrength, type EdgeKind, type EmailAttachment, type EmailSendInput, type EmailSendResult, type ExpandedNode, type ExplainConfigOverride, type ExplainNode, type ExplainOptions, type ExplainOpts, type ExplainRequest, type ExplainResult, type ExplainSibling, type ExplainWarning, type ListAnomaliesOptions, type ListAnomaliesResponse, type LoadManifestOptions, type MetricEdge, type MetricHandle, type MetricNode, type MetricScope, type MetricTree, MetricTreeClient, type MetricTreeHookResult, type OpportunityRequest, type OpportunityResult, type OxyAirwayApi, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppFunctionManifest, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyEmailApi, type OxyFetchResult, type OxyFunctionContext, type OxyFunctionHandler, type OxyFunctionRequest, type OxyFunctionRow, type OxyFunctionUser, type OxyInjectedAppConfig, type OxySecretsApi, type OxySemanticApi, type OxyStorageApi, type OxyWarehouseApi, type PredictChange, type PredictImpact, type PredictResult, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ResolvedCustomAppManifest, type ScanFailure, type ScanOptions, type ScanResponse, type SegmentOpportunity, type SemanticArrayOp, type SemanticDateRangeOp, type SemanticFilter, type SemanticScalarOp, type SemanticTimeDimension, type SensitivityDriver, type SensitivityResult, type SizeOpts, type SkippedDimension, type SplitKind, type StorageDownloadUrl, type StorageListPage, type StorageObject, type StoragePutOptions, type StoragePutResult, type StorageUploadUrl, type StorageUploadUrlInput, type TimeDimensionsResponse, type UseAgentRunInput, type UseAgentRunResult, type UseFunctionResult, type UseMeasureBreakdownResult, type UseMetricTreeOpts, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, type UseWorldModelGraphResult, type UseWorldModelInstancesOpts, type UseWorldModelInstancesResult, type WmBreakdownEdge, type WmBreakdownNode, type WmEntityCount, type WmFilterCountsResponse, type WmInstance, type WmInstancesResponse, type WmMeasureBreakdown, type WmMeasureBreakdownEvent, type WorldModel, type WorldModelApi, type WorldModelDimension, type WorldModelEdge, type WorldModelEntity, type WorldModelInducedMeasure, type WorldModelMeasure, WorldModelScopeUnsupportedError, _resetCustomAppManifestCacheForTest, apiErrorFromResponse, base64ToBytes, bytesToBase64, createWorldModel, getCustomAppDebug, getOxyAppLogger, interpretCustomAppError, loadCustomAppManifest, readInjectedAppConfig, readJsonSseStream, setOxyAppLogger, useAgentRun, useDistribution, useExplain, useFunction, useMeasureBreakdown, useMetricTree, useOpportunity, useOxyApp, usePredict, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useSensitivity, useTimeDimensions, useTrackEvent, useWorldModel, useWorldModelGraph, useWorldModelInstances };
 //# sourceMappingURL=index.d.mts.map