@oxy-hq/sdk 2.4.0 → 2.6.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-BLsczFL4.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-DnBdQ8dG.mjs";
 //#region src/config.d.ts
 /**
  * Configuration for the Oxy SDK
@@ -432,11 +432,11 @@ declare class AnomaliesClient {
   explain(anomalyId: string): Promise<ExplainResult>;
 }
 //#endregion
-//#region src/customer-app/debug.d.ts
+//#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 +460,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,6 +486,24 @@ 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 {
@@ -539,6 +557,25 @@ 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.
+   */
+  attachments?: EmailAttachment[];
+}
+/** One attachment on {@link EmailSendInput}. */
+interface EmailAttachment {
+  /** Filename shown to the recipient. Required; path separators are stripped. */
+  filename: string;
+  /** File bytes, **base64-encoded** (the only way binary crosses the isolate boundary). */
+  content: string;
+  /** 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 +586,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`);
@@ -574,14 +769,15 @@ interface OxyFunctionContext {
   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 +803,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 +813,5 @@ 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 };
+export { type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, AnomaliesClient, type Anomaly, type AnomalySeverity, type AnomalyStatus, type AppFetcher, type CustomAppDebugSnapshot, type CustomAppErrorReport, type DimensionOpportunity, type DriverAttribution, type DriverConfidence, type DriverDirection, type DriverForm, type DriverStrength, type EdgeKind, type EmailAttachment, 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 OxyStorageApi, type OxyWarehouseApi, type PredictChange, type PredictImpact, type PredictResult, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ResolvedCustomAppManifest, 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 StorageDownloadUrl, type StorageListPage, type StorageObject, type StoragePutOptions, type StoragePutResult, type StorageUploadUrl, type StorageUploadUrlInput, type UseAgentRunInput, type UseAgentRunResult, type UseFunctionResult, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, _resetCustomAppManifestCacheForTest, apiErrorFromResponse, getCustomAppDebug, getOxyAppLogger, interpretCustomAppError, loadCustomAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useFunction, useOxyApp, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/metricTree.ts","../src/anomalies.ts","../src/customer-app/debug.ts","../src/customer-app/function-context.ts","../src/customer-app/inject.ts","../src/customer-app/logger.ts"],"mappings":";;;;;;UAGiB;;;;EAIf;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;EAMA;;;;KCjCU;KACA;KACA;KACA;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA,MAAM;;EAEN;EACA,WAAW;EACX,UAAU;EACV,YAAY;EACZ;EACA,MAAM;EACN;EACA;EACA;EACA;;UAGe;EACf,OAAO;EACP,OAAO;EACP;;UAKe;EACf;EACA;EACA;EACA;EACA,OAAO;EACP,WAAW;EACX,UAAU;EACV;EACA;;UAGe;EACf;EACA,SAAS;;UAKM;EACf;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;;UAGe;EACf,QAAQ;EACR,SAAS;;KAKC;EACN;EAAmB;;EACnB;EAAmB;EAAmB;;EACtC;EAA6B;EAAmB;;EAChD;EAAuB;EAAmB;EAAe;;UAE9C;EACf,OAAO;EACP;EACA;EACA;;UAGe;EACf,OAAO;EACP;EACA;EACA;EACA;EACA;EACA,WAAW;EACX;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA,MAAM;EACN;EACA;;KAGU;EAEN;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;;UAGW;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA,SAAS;;UAGM;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,qBAAqB;EACrB;EACA,WAAW;;UAKI;EACf;EACA;EACA;EACA;EACA;;EAEA;;UAGe;EACf;EACA;;EAEA;EACA;EACA,UAAU;EACV;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;;EAEA;EACA,YAAY;EACZ,oBAAoB;EACpB,YAAY;;;;;;;KAUF,eAAa,GAAG,kBAAkB,UAAU,gBAAgB,QAAQ;;;;;;;;;;;;;;;;cAiBnE;mBACM;mBACA;EAEjB,YAAY,QAAQ,WAAW,SAAS;UAKhC;UAIA;;;;;;;;;;;;;EAmBF,QAAQ,gBAAgB,QAAQ;;;;;;;;;;;;;;EAkBhC,eAAe,oBAAoB,QAAQ;;;;;;;;;;;;EAkB3C,QAAQ,SAAS,kBAAkB,QAAQ;;;;;;;;;;;;;;;EAsB3C,QAAQ,SAAS,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;EAwB1C,kBAAkB,SAAS,qBAAqB,QAAQ;;;;KC7VpD;KACA;;;;;;UAOK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV,QAAQ;EACR;;EAEA,gBAAgB;EAChB;EACA;EACA;;UAGe;EACf,SAAS;;EAET;;UAGe;EACf,WAAW;;UAGI;;EAEf;;UAGe;EACf;EACA;EACA;;KAKU,aAAa,GAAG,kBAAkB,UAAU,gBAAgB,QAAQ;;;;;;;;;;;;;;cAenE;mBACM;mBACA;EAEjB,YAAY,QAAQ,WAAW,SAAS;UAKhC;UAIA;;;;;;;;;;EAgBF,KAAK,UAAS,uBAA4B,QAAQ;;;;;;;;;;;;;EAqBlD,KAAK,UAAS,cAAmB,QAAQ;;;;EAWzC,aAAa,mBAAmB,QAAQ,gBAAgB,QAAQ;;;;;EAYhE,QAAQ,oBAAoB,QAAQ;;;;;;;UCpI3B;EACf;EACA;EACA;IACE;IACA;IACA;IACA;IACA;IACA;IACA;;EAEF;EACA;;EAEA,UAAU;EACV;EACA,UAAU;IAAQ;IAAc;;;;;;;;;iBASZ,oBACpB,UAAU,8BACT,QAAQ;;;;;;;;;;;UChBM;;EAEf;;;KAMU,iBAAiB;;UAGZ;EACf;EACA;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf,OAAO,kBAAkB,eAAe,MAAM,mBAAmB;EACjE,KAAK,kBAAkB,cAAc;EACrC,OACE,kBACA,eACA,MAAM,kBACN,4BACC;;;UAIY;EACf,IAAI,aAAa,gBAAgB;;;UAIlB;EACf,MAAM,MAAM,0BAA0B;;;UAIvB;EACf,IAAI,qBAAqB,YAAY,iCAAiC;IAAU;;;;;;;;;UAWjE;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;UAIe;;EAEf;;;UAIe;EACf,KAAK,OAAO,iBAAiB,QAAQ;;;;;;;UAUtB;;EAEf,MAAM;;EAEN,KAAK;;EAEL,OAAO;;EAEP,MAAM,cAAc,QAAQ;;EAE5B,YACE,aACA;IAAS;MACR,eAAe;;EAElB,MAAM,aAAa,OAAO,cAAc,QAAQ;EAChD,WAAW;EACX,SAAS;EACT,UAAU;EACV,QAAQ;EACR,OAAO;;;KAIG,sBACV,KAAK,oBACL,KAAK,uBACF,QAAQ,YAAY;;;;;;;;UCjJR;EACf;EACA;EACA;EACA;EACA;EACA;;EAEA;;QAGM;YACI;IACR,cAAc;;;;;;;;;iBAUF,yBAAyB;;;KCpB7B;UAEK;EACf,IAAI,OAAO,gBAAgB,aAAa,MAAM;;;iBAMhC,gBAAgB,QAAQ;;iBAKxB,mBAAmB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/metricTree.ts","../src/anomalies.ts","../src/custom-app/debug.ts","../src/custom-app/function-context.ts","../src/custom-app/inject.ts","../src/custom-app/logger.ts"],"mappings":";;;;;;UAGiB;;;;EAIf;;;;EAKA;;;;EAKA;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;EAMA;;;;KCjCU;KACA;KACA;KACA;KACA;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA,MAAM;;EAEN;EACA,WAAW;EACX,UAAU;EACV,YAAY;EACZ;EACA,MAAM;EACN;EACA;EACA;EACA;;UAGe;EACf,OAAO;EACP,OAAO;EACP;;UAKe;EACf;EACA;EACA;EACA;EACA,OAAO;EACP,WAAW;EACX,UAAU;EACV;EACA;;UAGe;EACf;EACA,SAAS;;UAKM;EACf;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA,MAAM;EACN;;UAGe;EACf,QAAQ;EACR,SAAS;;KAKC;EACN;EAAmB;;EACnB;EAAmB;EAAmB;;EACtC;EAA6B;EAAmB;;EAChD;EAAuB;EAAmB;EAAe;;UAE9C;EACf,OAAO;EACP;EACA;EACA;;UAGe;EACf,OAAO;EACP;EACA;EACA;EACA;EACA;EACA,WAAW;EACX;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA,MAAM;EACN;EACA;;KAGU;EAEN;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;EACA;;EAGA;EACA;EACA;EACA;;UAGW;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA,SAAS;;UAGM;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO;EACP;EACA,qBAAqB;EACrB;EACA,WAAW;;UAKI;EACf;EACA;EACA;EACA;EACA;;EAEA;;UAGe;EACf;EACA;;EAEA;EACA;EACA,UAAU;EACV;;UAGe;EACf;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;;EAEA;EACA,YAAY;EACZ,oBAAoB;EACpB,YAAY;;;;;;;KAUF,eAAa,GAAG,kBAAkB,UAAU,gBAAgB,QAAQ;;;;;;;;;;;;;;;;cAiBnE;mBACM;mBACA;EAEjB,YAAY,QAAQ,WAAW,SAAS;UAKhC;UAIA;;;;;;;;;;;;;EAmBF,QAAQ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"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
-import { _ as interpretCustomerAppError, a as useFunction, c as useQuery, d as useTrackEvent, f as _resetCustomerAppManifestCacheForTest, g as apiErrorFromResponse, h as OxyApiError, i as useAgentRun, l as useResolvedManifest, m as readInjectedAppConfig, n as OxyAppProvider, o as useOxyApp, p as loadCustomerAppManifest, r as OxyChat, s as useProcedureRun, t as OxyAnswer, u as useSemanticQuery, v as getOxyAppLogger, y as setOxyAppLogger } from "./react-DArzs6_l.mjs";
+import { _ as interpretCustomAppError, a as useFunction, c as useQuery, d as useTrackEvent, f as _resetCustomAppManifestCacheForTest, g as apiErrorFromResponse, h as OxyApiError, i as useAgentRun, l as useResolvedManifest, m as readInjectedAppConfig, n as OxyAppProvider, o as useOxyApp, p as loadCustomAppManifest, r as OxyChat, s as useProcedureRun, t as OxyAnswer, u as useSemanticQuery, v as getOxyAppLogger, y as setOxyAppLogger } from "./react-5HGW_0oy.mjs";
 
 //#region src/anomalies.ts
 /**
@@ -82,14 +82,14 @@ var AnomaliesClient = class {
 };
 
 //#endregion
-//#region src/customer-app/debug.ts
+//#region src/custom-app/debug.ts
 /**
 * 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.
 */
-async function getCustomerAppDebug(resolved) {
+async function getCustomAppDebug(resolved) {
 	const log = getOxyAppLogger();
 	const { apiBaseUrl, orgSlug, appSlug } = resolved;
 	const url = `${apiBaseUrl}/api/customer-apps/${encodeURIComponent(orgSlug)}/${encodeURIComponent(appSlug)}/debug`;
@@ -233,5 +233,5 @@ var MetricTreeClient = class {
 };
 
 //#endregion
-export { AnomaliesClient, MetricTreeClient, OxyAnswer, OxyApiError, OxyAppProvider, OxyChat, _resetCustomerAppManifestCacheForTest, apiErrorFromResponse, getCustomerAppDebug, getOxyAppLogger, interpretCustomerAppError, loadCustomerAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useFunction, useOxyApp, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
+export { AnomaliesClient, MetricTreeClient, OxyAnswer, OxyApiError, OxyAppProvider, OxyChat, _resetCustomAppManifestCacheForTest, apiErrorFromResponse, getCustomAppDebug, getOxyAppLogger, interpretCustomAppError, loadCustomAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useFunction, useOxyApp, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/anomalies.ts","../src/customer-app/debug.ts","../src/metricTree.ts"],"sourcesContent":["// Anomaly inbox types + client. Surfaces the `/semantic/anomalies*`\n// endpoints — list, scan, status, explain — so SDK consumers can render\n// the same inbox the Oxy IDE uses.\n\nimport type { OxyConfig } from \"./config\";\nimport type { ExplainResult } from \"./metricTree\";\n\n// ── Types ────────────────────────────────────────────────────────────────────\n\nexport type AnomalyStatus = \"new\" | \"acknowledged\" | \"dismissed\";\nexport type AnomalySeverity = \"low\" | \"medium\" | \"high\";\n\n/**\n * One row in the anomaly inbox. Detected by `oxy-metric-monitoring` per\n * `.monitor.yml` entry; upserted by repeat scans so unresolved anomalies\n * stay visible without piling up duplicates.\n */\nexport interface Anomaly {\n  id: string;\n  workspace_id: string;\n  measure: string;\n  time_dimension: string;\n  granularity: string;\n  period_start: string;\n  period_end: string;\n  observed: number;\n  expected: number;\n  lower_bound: number;\n  upper_bound: number;\n  z_score: number;\n  severity: AnomalySeverity | string;\n  status: AnomalyStatus | string;\n  label?: string | null;\n  /** Cached ExplainResult — populated by `POST /anomalies/:id/explain`. */\n  explain_cache?: ExplainResult | null;\n  explain_cached_at?: string | null;\n  detected_at: string;\n  updated_at: string;\n}\n\nexport interface ListAnomaliesOptions {\n  status?: AnomalyStatus | string;\n  /** Max rows (server caps at 500, defaults to 100). */\n  limit?: number;\n}\n\nexport interface ListAnomaliesResponse {\n  anomalies: Anomaly[];\n}\n\nexport interface ScanOptions {\n  /** Override the reference \"now\" date (YYYY-MM-DD) — useful for demos. */\n  as_of?: string;\n}\n\nexport interface ScanResponse {\n  monitors_scanned: number;\n  monitors_failed: number;\n  anomalies_persisted: number;\n}\n\n// ── Client ───────────────────────────────────────────────────────────────────\n\nexport type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;\n\n/**\n * Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`\n * rather than instantiating directly — the getter wires the request helper\n * so auth, timeout, and branch propagation come along for free.\n *\n * @example\n * ```typescript\n * const { anomalies } = await client.anomalies.list({ status: \"new\" });\n * for (const a of anomalies) {\n *   console.log(a.label ?? a.measure, a.severity, a.z_score.toFixed(2));\n * }\n * ```\n */\nexport class AnomaliesClient {\n  private readonly request: RequestFn;\n  private readonly config: OxyConfig;\n\n  constructor(config: OxyConfig, request: RequestFn) {\n    this.config = config;\n    this.request = request;\n  }\n\n  private path(suffix: string): string {\n    return `/${this.config.projectId}/semantic/anomalies${suffix}`;\n  }\n\n  private buildQuery(extra: Record<string, string> = {}): string {\n    const params: Record<string, string> = { ...extra };\n    if (this.config.branch) params.branch = this.config.branch;\n    const qs = new URLSearchParams(params).toString();\n    return qs ? `?${qs}` : \"\";\n  }\n\n  /**\n   * List anomalies in the inbox, newest first.\n   *\n   * @example\n   * ```typescript\n   * // Open / unresolved anomalies only\n   * const { anomalies } = await client.anomalies.list({ status: \"new\" });\n   * ```\n   */\n  async list(options: ListAnomaliesOptions = {}): Promise<ListAnomaliesResponse> {\n    const extra: Record<string, string> = {};\n    if (options.status) extra.status = options.status;\n    if (options.limit) extra.limit = String(options.limit);\n    // No trailing slash before the query — axum 307-redirects \"/anomalies/\"\n    // to \"/anomalies\", and the redirect fails CORS preflight in browsers.\n    return this.request<ListAnomaliesResponse>(this.path(this.buildQuery(extra)));\n  }\n\n  /**\n   * Trigger a full scan. Iterates every `.monitor.yml` entry in the\n   * workspace, runs the detector, and upserts matching rows into the\n   * inbox. Returns counts of scanned / failed / persisted.\n   *\n   * @example\n   * ```typescript\n   * // Scan against a known-good reference date (matches the seed dataset)\n   * const result = await client.anomalies.scan({ as_of: \"2025-12-15\" });\n   * console.log(`${result.anomalies_persisted} anomalies detected`);\n   * ```\n   */\n  async scan(options: ScanOptions = {}): Promise<ScanResponse> {\n    const extra: Record<string, string> = {};\n    if (options.as_of) extra.as_of = options.as_of;\n    return this.request<ScanResponse>(this.path(`/scan${this.buildQuery(extra)}`), {\n      method: \"POST\"\n    });\n  }\n\n  /**\n   * Update an anomaly's status (acknowledge / dismiss / re-open).\n   */\n  async updateStatus(anomalyId: string, status: AnomalyStatus): Promise<Anomaly> {\n    const query = this.buildQuery();\n    return this.request<Anomaly>(this.path(`/${encodeURIComponent(anomalyId)}/status${query}`), {\n      method: \"POST\",\n      body: JSON.stringify({ status })\n    });\n  }\n\n  /**\n   * Run the metric-tree `explain` for an anomaly and cache the result on\n   * the row. Subsequent calls return the cached `ExplainResult` instantly.\n   */\n  async explain(anomalyId: string): Promise<ExplainResult> {\n    const query = this.buildQuery();\n    return this.request<ExplainResult>(\n      this.path(`/${encodeURIComponent(anomalyId)}/explain${query}`),\n      { method: \"POST\" }\n    );\n  }\n}\n","// Bundle-side accessor for the server's diagnostic snapshot.\n//\n// `GET /api/customer-apps/<org>/<app>/debug` returns a structured\n// snapshot of what oxy currently sees about a registered customer\n// app: the app row, bundle dir resolution, and parsed manifest (or\n// parse error). Useful when a bundle isn't loading what you expected\n// and you want to verify what the server actually sees — without\n// needing terminal access.\n//\n// The `products` field on the snapshot is a legacy artifact carried\n// for server-side compatibility; in v2 the bundle owns its queries\n// via `useQuery` and the field is always empty for v2 manifests.\n\nimport { getOxyAppLogger } from \"./logger\";\nimport type { ResolvedCustomerAppManifest } from \"./manifest\";\n\n/** Untyped at the boundary — keep it loose so server-side schema\n * additions don't break older bundles. Stable enough for inspection\n * but not a contract clients should depend on field-by-field. */\nexport interface CustomerAppDebugSnapshot {\n  org_slug: string;\n  app_slug: string;\n  app: {\n    id: string;\n    slug: string;\n    name: string;\n    status: string;\n    source_type: string;\n    project_id: string;\n    branch: string;\n  };\n  bundle_dir: string | null;\n  bundle_dir_exists: boolean;\n  /** Raw parsed manifest from the server — kept loose so schema additions don't break older bundles. */\n  manifest: Record<string, unknown> | null;\n  manifest_error: string | null;\n  products: Array<{ name: string; producer: string }>;\n}\n\n/**\n * Fetch the server-side diagnostic snapshot for this bundle. Pair with\n * `loadCustomerAppManifest()` — pass its result here. Logs the\n * snapshot through the SDK logger so it appears in the bundle's\n * console at info level.\n */\nexport async function getCustomerAppDebug(\n  resolved: ResolvedCustomerAppManifest\n): Promise<CustomerAppDebugSnapshot> {\n  const log = getOxyAppLogger();\n  const { apiBaseUrl, orgSlug, appSlug } = resolved;\n  const url =\n    `${apiBaseUrl}/api/customer-apps/` +\n    `${encodeURIComponent(orgSlug)}/${encodeURIComponent(appSlug)}/debug`;\n\n  log.log(\"debug\", \"fetching debug snapshot\", { url });\n  const res = await fetch(url, { credentials: \"same-origin\" });\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new Error(\n      `Failed to fetch debug snapshot (HTTP ${res.status}): ${detail || res.statusText}`\n    );\n  }\n  const snapshot = (await res.json()) as CustomerAppDebugSnapshot;\n  log.log(\"info\", \"debug snapshot\", snapshot as unknown as Record<string, unknown>);\n  return snapshot;\n}\n","// Metric-tree types + client. Mirrors `airlayer::engine::metric_tree*`\n// over the `/<project_id>/semantic/metric-tree*` HTTP endpoints. Serde\n// emits snake_case so these field names match the wire format verbatim.\n\nimport type { OxyConfig } from \"./config\";\n\n// ── Tree ──────────────────────────────────────────────────────────────────────\n\nexport type EdgeKind = \"component\" | \"driver\";\nexport type DriverDirection = \"positive\" | \"negative\" | \"unknown\";\nexport type DriverStrength = \"strong\" | \"moderate\" | \"weak\";\nexport type DriverConfidence = \"high\" | \"medium\" | \"low\";\nexport type DriverForm = \"linear\" | \"log-log\" | \"log-linear\" | \"linear-log\";\n\nexport interface MetricNode {\n  id: string;\n  view: string;\n  measure: string;\n  label: string;\n  description?: string | null;\n  measure_type: string;\n  is_composite: boolean;\n  expr?: string | null;\n}\n\nexport interface MetricEdge {\n  from: string;\n  to: string;\n  kind: EdgeKind;\n  /** Sign of a component edge; omitted (defaults to +1) for most edges. */\n  sign?: number;\n  direction: DriverDirection;\n  strength: DriverStrength;\n  confidence: DriverConfidence;\n  coefficient?: number | null;\n  form: DriverForm;\n  intercept?: number | null;\n  lag?: number | null;\n  description?: string | null;\n  refs?: string[] | null;\n}\n\nexport interface MetricTree {\n  nodes: MetricNode[];\n  edges: MetricEdge[];\n  root?: string | null;\n}\n\n// ── Sensitivity ──────────────────────────────────────────────────────────────\n\nexport interface SensitivityDriver {\n  measure: string;\n  path: string[];\n  edge_kind: string;\n  effective_coefficient?: number | null;\n  form?: DriverForm | null;\n  direction: DriverDirection;\n  strength: DriverStrength;\n  lag?: number | null;\n  description?: string | null;\n}\n\nexport interface SensitivityResult {\n  target: string;\n  drivers: SensitivityDriver[];\n}\n\n// ── Predict ──────────────────────────────────────────────────────────────────\n\nexport interface PredictChange {\n  measure: string;\n  delta: number;\n}\n\nexport interface PredictImpact {\n  measure: string;\n  estimated_delta: number;\n  confidence: string;\n  path: string[];\n  form: DriverForm;\n  lag?: number | null;\n}\n\nexport interface PredictResult {\n  inputs: PredictChange[];\n  impacts: PredictImpact[];\n}\n\n// ── Explain (RCA) ────────────────────────────────────────────────────────────\n\nexport type SplitKind =\n  | { type: \"component\"; child_measure: string }\n  | { type: \"dimension\"; dimension: string; value: string }\n  | { type: \"uniform_degradation\"; dimension: string; num_elements: number }\n  | { type: \"cross_cutting\"; dimension: string; value: string; measures: string[] };\n\nexport interface ExplainSibling {\n  split: SplitKind;\n  measure: string;\n  delta: number;\n  root_fraction: number;\n}\n\nexport interface ExplainNode {\n  split: SplitKind;\n  measure: string;\n  filters: unknown[];\n  delta: number;\n  concentration: number;\n  root_fraction: number;\n  siblings?: ExplainSibling[];\n  dimension_count?: number;\n  children?: ExplainNode[];\n}\n\nexport interface DriverAttribution {\n  driver_measure: string;\n  driver_previous: number;\n  driver_current: number;\n  driver_delta: number;\n  coefficient?: number;\n  form: DriverForm;\n  estimated_target_impact?: number;\n  description?: string;\n}\n\nexport type ExplainWarning =\n  | {\n      type: \"simpsons_paradox\";\n      dimension: string;\n      aggregate_delta: number;\n      segment_directions: [string, number][];\n    }\n  | {\n      type: \"opposing_offset\";\n      component_a: string;\n      component_b: string;\n      delta_a: number;\n      delta_b: number;\n    }\n  | {\n      type: \"non_additive_dimension_split\";\n      measure: string;\n      measure_type: string;\n      dimension: string;\n    };\n\nexport interface ExplainConfigOverride {\n  deep?: boolean;\n  max_depth?: number;\n  coverage_threshold?: number;\n}\n\nexport interface ExplainRequest {\n  target: string;\n  time_dimension: string;\n  current_period: [string, string];\n  previous_period: [string, string];\n  config?: ExplainConfigOverride;\n}\n\nexport interface ExplainResult {\n  target: string;\n  target_delta: number;\n  target_previous: number;\n  target_current: number;\n  time_dimension: string;\n  current_period: [string, string];\n  previous_period: [string, string];\n  nodes: ExplainNode[];\n  coverage: number;\n  driver_attribution?: DriverAttribution[];\n  alternatives?: unknown[];\n  warnings?: ExplainWarning[];\n}\n\n// ── Opportunity ──────────────────────────────────────────────────────────────\n\nexport interface SegmentOpportunity {\n  segment: string;\n  current_value: number;\n  volume: number;\n  benchmark: number;\n  gap: number;\n  /** Match-the-best upside in measure units. */\n  upside: number;\n}\n\nexport interface DimensionOpportunity {\n  dimension: string;\n  cardinality: number;\n  /** \"best_peer\" or \"p75\". */\n  benchmark_basis: string;\n  total_upside: number;\n  segments: SegmentOpportunity[];\n  other_segments_skipped: number;\n}\n\nexport interface SkippedDimension {\n  dimension: string;\n  reason: string;\n}\n\nexport interface OpportunityRequest {\n  target: string;\n  time_dimension: string;\n  period: [string, string];\n}\n\nexport interface OpportunityResult {\n  target: string;\n  period: [string, string];\n  overall_value: number;\n  /** \"value_share\" (additive) or \"equal\" (ratios). */\n  weight_basis: string;\n  dimensions: DimensionOpportunity[];\n  skipped_dimensions: SkippedDimension[];\n  downstream: PredictImpact[];\n}\n\n// ── Client ───────────────────────────────────────────────────────────────────\n\n/**\n * Shape of the inner request helper exposed by `OxyClient`. The metric-tree\n * client reuses it to inherit auth headers, timeout, baseUrl, and project\n * scoping rather than reimplementing fetch end-to-end.\n */\nexport type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;\n\n/**\n * Client for the `/semantic/metric-tree*` endpoints. Surfaces the four\n * airlayer metric-tree analyses (tree introspection, sensitivity, predict,\n * explain, opportunity) over typed methods.\n *\n * Construction is internal to {@link OxyClient} — call `client.metricTree`\n * to access an instance rather than building one yourself.\n *\n * @example\n * ```typescript\n * const client = await OxyClient.create({ projectId: \"...\", apiKey: \"...\" });\n * const tree = await client.metricTree.getTree();\n * const drivers = await client.metricTree.getSensitivity(\"orders.net_revenue\");\n * ```\n */\nexport class MetricTreeClient {\n  private readonly request: RequestFn;\n  private readonly config: OxyConfig;\n\n  constructor(config: OxyConfig, request: RequestFn) {\n    this.config = config;\n    this.request = request;\n  }\n\n  private path(suffix: string): string {\n    return `/${this.config.projectId}/semantic/metric-tree${suffix}`;\n  }\n\n  private buildQuery(extra: Record<string, string> = {}): string {\n    const params: Record<string, string> = { ...extra };\n    if (this.config.branch) params.branch = this.config.branch;\n    const qs = new URLSearchParams(params).toString();\n    return qs ? `?${qs}` : \"\";\n  }\n\n  /**\n   * Fetch the full metric tree, or the subtree rooted at `root`.\n   *\n   * @param root - Optional fully-qualified measure id to root the tree at.\n   * @returns Nodes (measures) and edges (component / driver relationships).\n   *\n   * @example\n   * ```typescript\n   * const tree = await client.metricTree.getTree();\n   * const subtree = await client.metricTree.getTree(\"orders.net_revenue\");\n   * ```\n   */\n  async getTree(root?: string): Promise<MetricTree> {\n    const query = this.buildQuery(root ? { root } : {});\n    return this.request<MetricTree>(this.path(query));\n  }\n\n  /**\n   * Rank the declared drivers of a measure by influence.\n   *\n   * @param measureId - Fully-qualified measure id (`view.measure`).\n   *\n   * @example\n   * ```typescript\n   * const sensitivity = await client.metricTree.getSensitivity(\"orders.net_revenue\");\n   * for (const driver of sensitivity.drivers) {\n   *   console.log(driver.measure, driver.direction, driver.strength);\n   * }\n   * ```\n   */\n  async getSensitivity(measureId: string): Promise<SensitivityResult> {\n    const query = this.buildQuery();\n    return this.request<SensitivityResult>(\n      this.path(`/${encodeURIComponent(measureId)}/sensitivity${query}`)\n    );\n  }\n\n  /**\n   * Propagate hypothetical `(measure, delta)` changes upward through the\n   * tree. Returns the estimated impact on every downstream measure.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.predict([\n   *   { measure: \"marketing_spend.total_spend\", delta: 10000 },\n   * ]);\n   * ```\n   */\n  async predict(changes: PredictChange[]): Promise<PredictResult> {\n    const query = this.buildQuery();\n    return this.request<PredictResult>(this.path(`/predict${query}`), {\n      method: \"POST\",\n      body: JSON.stringify({ changes })\n    });\n  }\n\n  /**\n   * Period-over-period root-cause decomposition. Recursively splits the\n   * target measure by components and dimensions until the move concentrates.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.explain({\n   *   target: \"financials.operating_profit\",\n   *   time_dimension: \"financials.month\",\n   *   current_period: [\"2025-09-01\", \"2025-09-30\"],\n   *   previous_period: [\"2025-08-01\", \"2025-08-31\"],\n   * });\n   * ```\n   */\n  async explain(request: ExplainRequest): Promise<ExplainResult> {\n    const query = this.buildQuery();\n    return this.request<ExplainResult>(this.path(`/explain${query}`), {\n      method: \"POST\",\n      body: JSON.stringify(request)\n    });\n  }\n\n  /**\n   * Size the upside opportunity for a measure by finding underperforming\n   * segments. Skips high-cardinality dimensions and trims the long tail.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.findOpportunities({\n   *   target: \"orders.net_revenue\",\n   *   time_dimension: \"orders.order_date\",\n   *   period: [\"2025-09-01\", \"2025-09-30\"],\n   * });\n   * for (const dim of result.dimensions) {\n   *   console.log(dim.dimension, \"+\", dim.total_upside);\n   * }\n   * ```\n   */\n  async findOpportunities(request: OpportunityRequest): Promise<OpportunityResult> {\n    const query = this.buildQuery();\n    return this.request<OpportunityResult>(this.path(`/opportunity${query}`), {\n      method: \"POST\",\n      body: JSON.stringify(request)\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/anomalies.ts","../src/custom-app/debug.ts","../src/metricTree.ts"],"sourcesContent":["// Anomaly inbox types + client. Surfaces the `/semantic/anomalies*`\n// endpoints — list, scan, status, explain — so SDK consumers can render\n// the same inbox the Oxy IDE uses.\n\nimport type { OxyConfig } from \"./config\";\nimport type { ExplainResult } from \"./metricTree\";\n\n// ── Types ────────────────────────────────────────────────────────────────────\n\nexport type AnomalyStatus = \"new\" | \"acknowledged\" | \"dismissed\";\nexport type AnomalySeverity = \"low\" | \"medium\" | \"high\";\n\n/**\n * One row in the anomaly inbox. Detected by `oxy-metric-monitoring` per\n * `.monitor.yml` entry; upserted by repeat scans so unresolved anomalies\n * stay visible without piling up duplicates.\n */\nexport interface Anomaly {\n  id: string;\n  workspace_id: string;\n  measure: string;\n  time_dimension: string;\n  granularity: string;\n  period_start: string;\n  period_end: string;\n  observed: number;\n  expected: number;\n  lower_bound: number;\n  upper_bound: number;\n  z_score: number;\n  severity: AnomalySeverity | string;\n  status: AnomalyStatus | string;\n  label?: string | null;\n  /** Cached ExplainResult — populated by `POST /anomalies/:id/explain`. */\n  explain_cache?: ExplainResult | null;\n  explain_cached_at?: string | null;\n  detected_at: string;\n  updated_at: string;\n}\n\nexport interface ListAnomaliesOptions {\n  status?: AnomalyStatus | string;\n  /** Max rows (server caps at 500, defaults to 100). */\n  limit?: number;\n}\n\nexport interface ListAnomaliesResponse {\n  anomalies: Anomaly[];\n}\n\nexport interface ScanOptions {\n  /** Override the reference \"now\" date (YYYY-MM-DD) — useful for demos. */\n  as_of?: string;\n}\n\nexport interface ScanResponse {\n  monitors_scanned: number;\n  monitors_failed: number;\n  anomalies_persisted: number;\n}\n\n// ── Client ───────────────────────────────────────────────────────────────────\n\nexport type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;\n\n/**\n * Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`\n * rather than instantiating directly — the getter wires the request helper\n * so auth, timeout, and branch propagation come along for free.\n *\n * @example\n * ```typescript\n * const { anomalies } = await client.anomalies.list({ status: \"new\" });\n * for (const a of anomalies) {\n *   console.log(a.label ?? a.measure, a.severity, a.z_score.toFixed(2));\n * }\n * ```\n */\nexport class AnomaliesClient {\n  private readonly request: RequestFn;\n  private readonly config: OxyConfig;\n\n  constructor(config: OxyConfig, request: RequestFn) {\n    this.config = config;\n    this.request = request;\n  }\n\n  private path(suffix: string): string {\n    return `/${this.config.projectId}/semantic/anomalies${suffix}`;\n  }\n\n  private buildQuery(extra: Record<string, string> = {}): string {\n    const params: Record<string, string> = { ...extra };\n    if (this.config.branch) params.branch = this.config.branch;\n    const qs = new URLSearchParams(params).toString();\n    return qs ? `?${qs}` : \"\";\n  }\n\n  /**\n   * List anomalies in the inbox, newest first.\n   *\n   * @example\n   * ```typescript\n   * // Open / unresolved anomalies only\n   * const { anomalies } = await client.anomalies.list({ status: \"new\" });\n   * ```\n   */\n  async list(options: ListAnomaliesOptions = {}): Promise<ListAnomaliesResponse> {\n    const extra: Record<string, string> = {};\n    if (options.status) extra.status = options.status;\n    if (options.limit) extra.limit = String(options.limit);\n    // No trailing slash before the query — axum 307-redirects \"/anomalies/\"\n    // to \"/anomalies\", and the redirect fails CORS preflight in browsers.\n    return this.request<ListAnomaliesResponse>(this.path(this.buildQuery(extra)));\n  }\n\n  /**\n   * Trigger a full scan. Iterates every `.monitor.yml` entry in the\n   * workspace, runs the detector, and upserts matching rows into the\n   * inbox. Returns counts of scanned / failed / persisted.\n   *\n   * @example\n   * ```typescript\n   * // Scan against a known-good reference date (matches the seed dataset)\n   * const result = await client.anomalies.scan({ as_of: \"2025-12-15\" });\n   * console.log(`${result.anomalies_persisted} anomalies detected`);\n   * ```\n   */\n  async scan(options: ScanOptions = {}): Promise<ScanResponse> {\n    const extra: Record<string, string> = {};\n    if (options.as_of) extra.as_of = options.as_of;\n    return this.request<ScanResponse>(this.path(`/scan${this.buildQuery(extra)}`), {\n      method: \"POST\"\n    });\n  }\n\n  /**\n   * Update an anomaly's status (acknowledge / dismiss / re-open).\n   */\n  async updateStatus(anomalyId: string, status: AnomalyStatus): Promise<Anomaly> {\n    const query = this.buildQuery();\n    return this.request<Anomaly>(this.path(`/${encodeURIComponent(anomalyId)}/status${query}`), {\n      method: \"POST\",\n      body: JSON.stringify({ status })\n    });\n  }\n\n  /**\n   * Run the metric-tree `explain` for an anomaly and cache the result on\n   * the row. Subsequent calls return the cached `ExplainResult` instantly.\n   */\n  async explain(anomalyId: string): Promise<ExplainResult> {\n    const query = this.buildQuery();\n    return this.request<ExplainResult>(\n      this.path(`/${encodeURIComponent(anomalyId)}/explain${query}`),\n      { method: \"POST\" }\n    );\n  }\n}\n","// Bundle-side accessor for the server's diagnostic snapshot.\n//\n// `GET /api/customer-apps/<org>/<app>/debug` returns a structured\n// snapshot of what oxy currently sees about a registered customer\n// app: the app row, bundle dir resolution, and parsed manifest (or\n// parse error). Useful when a bundle isn't loading what you expected\n// and you want to verify what the server actually sees — without\n// needing terminal access.\n//\n// The `products` field on the snapshot is a legacy artifact carried\n// for server-side compatibility; in v2 the bundle owns its queries\n// via `useQuery` and the field is always empty for v2 manifests.\n\nimport { getOxyAppLogger } from \"./logger\";\nimport type { ResolvedCustomAppManifest } from \"./manifest\";\n\n/** Untyped at the boundary — keep it loose so server-side schema\n * additions don't break older bundles. Stable enough for inspection\n * but not a contract clients should depend on field-by-field. */\nexport interface CustomAppDebugSnapshot {\n  org_slug: string;\n  app_slug: string;\n  app: {\n    id: string;\n    slug: string;\n    name: string;\n    status: string;\n    source_type: string;\n    project_id: string;\n    branch: string;\n  };\n  bundle_dir: string | null;\n  bundle_dir_exists: boolean;\n  /** Raw parsed manifest from the server — kept loose so schema additions don't break older bundles. */\n  manifest: Record<string, unknown> | null;\n  manifest_error: string | null;\n  products: Array<{ name: string; producer: string }>;\n}\n\n/**\n * Fetch the server-side diagnostic snapshot for this bundle. Pair with\n * `loadCustomAppManifest()` — pass its result here. Logs the\n * snapshot through the SDK logger so it appears in the bundle's\n * console at info level.\n */\nexport async function getCustomAppDebug(\n  resolved: ResolvedCustomAppManifest\n): Promise<CustomAppDebugSnapshot> {\n  const log = getOxyAppLogger();\n  const { apiBaseUrl, orgSlug, appSlug } = resolved;\n  const url =\n    `${apiBaseUrl}/api/customer-apps/` +\n    `${encodeURIComponent(orgSlug)}/${encodeURIComponent(appSlug)}/debug`;\n\n  log.log(\"debug\", \"fetching debug snapshot\", { url });\n  const res = await fetch(url, { credentials: \"same-origin\" });\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new Error(\n      `Failed to fetch debug snapshot (HTTP ${res.status}): ${detail || res.statusText}`\n    );\n  }\n  const snapshot = (await res.json()) as CustomAppDebugSnapshot;\n  log.log(\"info\", \"debug snapshot\", snapshot as unknown as Record<string, unknown>);\n  return snapshot;\n}\n","// Metric-tree types + client. Mirrors `airlayer::engine::metric_tree*`\n// over the `/<project_id>/semantic/metric-tree*` HTTP endpoints. Serde\n// emits snake_case so these field names match the wire format verbatim.\n\nimport type { OxyConfig } from \"./config\";\n\n// ── Tree ──────────────────────────────────────────────────────────────────────\n\nexport type EdgeKind = \"component\" | \"driver\";\nexport type DriverDirection = \"positive\" | \"negative\" | \"unknown\";\nexport type DriverStrength = \"strong\" | \"moderate\" | \"weak\";\nexport type DriverConfidence = \"high\" | \"medium\" | \"low\";\nexport type DriverForm = \"linear\" | \"log-log\" | \"log-linear\" | \"linear-log\";\n\nexport interface MetricNode {\n  id: string;\n  view: string;\n  measure: string;\n  label: string;\n  description?: string | null;\n  measure_type: string;\n  is_composite: boolean;\n  expr?: string | null;\n}\n\nexport interface MetricEdge {\n  from: string;\n  to: string;\n  kind: EdgeKind;\n  /** Sign of a component edge; omitted (defaults to +1) for most edges. */\n  sign?: number;\n  direction: DriverDirection;\n  strength: DriverStrength;\n  confidence: DriverConfidence;\n  coefficient?: number | null;\n  form: DriverForm;\n  intercept?: number | null;\n  lag?: number | null;\n  description?: string | null;\n  refs?: string[] | null;\n}\n\nexport interface MetricTree {\n  nodes: MetricNode[];\n  edges: MetricEdge[];\n  root?: string | null;\n}\n\n// ── Sensitivity ──────────────────────────────────────────────────────────────\n\nexport interface SensitivityDriver {\n  measure: string;\n  path: string[];\n  edge_kind: string;\n  effective_coefficient?: number | null;\n  form?: DriverForm | null;\n  direction: DriverDirection;\n  strength: DriverStrength;\n  lag?: number | null;\n  description?: string | null;\n}\n\nexport interface SensitivityResult {\n  target: string;\n  drivers: SensitivityDriver[];\n}\n\n// ── Predict ──────────────────────────────────────────────────────────────────\n\nexport interface PredictChange {\n  measure: string;\n  delta: number;\n}\n\nexport interface PredictImpact {\n  measure: string;\n  estimated_delta: number;\n  confidence: string;\n  path: string[];\n  form: DriverForm;\n  lag?: number | null;\n}\n\nexport interface PredictResult {\n  inputs: PredictChange[];\n  impacts: PredictImpact[];\n}\n\n// ── Explain (RCA) ────────────────────────────────────────────────────────────\n\nexport type SplitKind =\n  | { type: \"component\"; child_measure: string }\n  | { type: \"dimension\"; dimension: string; value: string }\n  | { type: \"uniform_degradation\"; dimension: string; num_elements: number }\n  | { type: \"cross_cutting\"; dimension: string; value: string; measures: string[] };\n\nexport interface ExplainSibling {\n  split: SplitKind;\n  measure: string;\n  delta: number;\n  root_fraction: number;\n}\n\nexport interface ExplainNode {\n  split: SplitKind;\n  measure: string;\n  filters: unknown[];\n  delta: number;\n  concentration: number;\n  root_fraction: number;\n  siblings?: ExplainSibling[];\n  dimension_count?: number;\n  children?: ExplainNode[];\n}\n\nexport interface DriverAttribution {\n  driver_measure: string;\n  driver_previous: number;\n  driver_current: number;\n  driver_delta: number;\n  coefficient?: number;\n  form: DriverForm;\n  estimated_target_impact?: number;\n  description?: string;\n}\n\nexport type ExplainWarning =\n  | {\n      type: \"simpsons_paradox\";\n      dimension: string;\n      aggregate_delta: number;\n      segment_directions: [string, number][];\n    }\n  | {\n      type: \"opposing_offset\";\n      component_a: string;\n      component_b: string;\n      delta_a: number;\n      delta_b: number;\n    }\n  | {\n      type: \"non_additive_dimension_split\";\n      measure: string;\n      measure_type: string;\n      dimension: string;\n    };\n\nexport interface ExplainConfigOverride {\n  deep?: boolean;\n  max_depth?: number;\n  coverage_threshold?: number;\n}\n\nexport interface ExplainRequest {\n  target: string;\n  time_dimension: string;\n  current_period: [string, string];\n  previous_period: [string, string];\n  config?: ExplainConfigOverride;\n}\n\nexport interface ExplainResult {\n  target: string;\n  target_delta: number;\n  target_previous: number;\n  target_current: number;\n  time_dimension: string;\n  current_period: [string, string];\n  previous_period: [string, string];\n  nodes: ExplainNode[];\n  coverage: number;\n  driver_attribution?: DriverAttribution[];\n  alternatives?: unknown[];\n  warnings?: ExplainWarning[];\n}\n\n// ── Opportunity ──────────────────────────────────────────────────────────────\n\nexport interface SegmentOpportunity {\n  segment: string;\n  current_value: number;\n  volume: number;\n  benchmark: number;\n  gap: number;\n  /** Match-the-best upside in measure units. */\n  upside: number;\n}\n\nexport interface DimensionOpportunity {\n  dimension: string;\n  cardinality: number;\n  /** \"best_peer\" or \"p75\". */\n  benchmark_basis: string;\n  total_upside: number;\n  segments: SegmentOpportunity[];\n  other_segments_skipped: number;\n}\n\nexport interface SkippedDimension {\n  dimension: string;\n  reason: string;\n}\n\nexport interface OpportunityRequest {\n  target: string;\n  time_dimension: string;\n  period: [string, string];\n}\n\nexport interface OpportunityResult {\n  target: string;\n  period: [string, string];\n  overall_value: number;\n  /** \"value_share\" (additive) or \"equal\" (ratios). */\n  weight_basis: string;\n  dimensions: DimensionOpportunity[];\n  skipped_dimensions: SkippedDimension[];\n  downstream: PredictImpact[];\n}\n\n// ── Client ───────────────────────────────────────────────────────────────────\n\n/**\n * Shape of the inner request helper exposed by `OxyClient`. The metric-tree\n * client reuses it to inherit auth headers, timeout, baseUrl, and project\n * scoping rather than reimplementing fetch end-to-end.\n */\nexport type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;\n\n/**\n * Client for the `/semantic/metric-tree*` endpoints. Surfaces the four\n * airlayer metric-tree analyses (tree introspection, sensitivity, predict,\n * explain, opportunity) over typed methods.\n *\n * Construction is internal to {@link OxyClient} — call `client.metricTree`\n * to access an instance rather than building one yourself.\n *\n * @example\n * ```typescript\n * const client = await OxyClient.create({ projectId: \"...\", apiKey: \"...\" });\n * const tree = await client.metricTree.getTree();\n * const drivers = await client.metricTree.getSensitivity(\"orders.net_revenue\");\n * ```\n */\nexport class MetricTreeClient {\n  private readonly request: RequestFn;\n  private readonly config: OxyConfig;\n\n  constructor(config: OxyConfig, request: RequestFn) {\n    this.config = config;\n    this.request = request;\n  }\n\n  private path(suffix: string): string {\n    return `/${this.config.projectId}/semantic/metric-tree${suffix}`;\n  }\n\n  private buildQuery(extra: Record<string, string> = {}): string {\n    const params: Record<string, string> = { ...extra };\n    if (this.config.branch) params.branch = this.config.branch;\n    const qs = new URLSearchParams(params).toString();\n    return qs ? `?${qs}` : \"\";\n  }\n\n  /**\n   * Fetch the full metric tree, or the subtree rooted at `root`.\n   *\n   * @param root - Optional fully-qualified measure id to root the tree at.\n   * @returns Nodes (measures) and edges (component / driver relationships).\n   *\n   * @example\n   * ```typescript\n   * const tree = await client.metricTree.getTree();\n   * const subtree = await client.metricTree.getTree(\"orders.net_revenue\");\n   * ```\n   */\n  async getTree(root?: string): Promise<MetricTree> {\n    const query = this.buildQuery(root ? { root } : {});\n    return this.request<MetricTree>(this.path(query));\n  }\n\n  /**\n   * Rank the declared drivers of a measure by influence.\n   *\n   * @param measureId - Fully-qualified measure id (`view.measure`).\n   *\n   * @example\n   * ```typescript\n   * const sensitivity = await client.metricTree.getSensitivity(\"orders.net_revenue\");\n   * for (const driver of sensitivity.drivers) {\n   *   console.log(driver.measure, driver.direction, driver.strength);\n   * }\n   * ```\n   */\n  async getSensitivity(measureId: string): Promise<SensitivityResult> {\n    const query = this.buildQuery();\n    return this.request<SensitivityResult>(\n      this.path(`/${encodeURIComponent(measureId)}/sensitivity${query}`)\n    );\n  }\n\n  /**\n   * Propagate hypothetical `(measure, delta)` changes upward through the\n   * tree. Returns the estimated impact on every downstream measure.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.predict([\n   *   { measure: \"marketing_spend.total_spend\", delta: 10000 },\n   * ]);\n   * ```\n   */\n  async predict(changes: PredictChange[]): Promise<PredictResult> {\n    const query = this.buildQuery();\n    return this.request<PredictResult>(this.path(`/predict${query}`), {\n      method: \"POST\",\n      body: JSON.stringify({ changes })\n    });\n  }\n\n  /**\n   * Period-over-period root-cause decomposition. Recursively splits the\n   * target measure by components and dimensions until the move concentrates.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.explain({\n   *   target: \"financials.operating_profit\",\n   *   time_dimension: \"financials.month\",\n   *   current_period: [\"2025-09-01\", \"2025-09-30\"],\n   *   previous_period: [\"2025-08-01\", \"2025-08-31\"],\n   * });\n   * ```\n   */\n  async explain(request: ExplainRequest): Promise<ExplainResult> {\n    const query = this.buildQuery();\n    return this.request<ExplainResult>(this.path(`/explain${query}`), {\n      method: \"POST\",\n      body: JSON.stringify(request)\n    });\n  }\n\n  /**\n   * Size the upside opportunity for a measure by finding underperforming\n   * segments. Skips high-cardinality dimensions and trims the long tail.\n   *\n   * @example\n   * ```typescript\n   * const result = await client.metricTree.findOpportunities({\n   *   target: \"orders.net_revenue\",\n   *   time_dimension: \"orders.order_date\",\n   *   period: [\"2025-09-01\", \"2025-09-30\"],\n   * });\n   * for (const dim of result.dimensions) {\n   *   console.log(dim.dimension, \"+\", dim.total_upside);\n   * }\n   * ```\n   */\n  async findOpportunities(request: OpportunityRequest): Promise<OpportunityResult> {\n    const query = this.buildQuery();\n    return this.request<OpportunityResult>(this.path(`/opportunity${query}`), {\n      method: \"POST\",\n      body: JSON.stringify(request)\n    });\n  }\n}\n"],"mappings":"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"}