@oxy-hq/sdk 2.0.1 → 2.3.0

package/dist/index.d.cts

@@ -1,7 +1,522 @@
 
 import * as React from "react";
-
+//#region src/config.d.ts
+/**
+ * Configuration for the Oxy SDK
+ */
+interface OxyConfig {
+  /**
+   * Base URL of the Oxy API (e.g., 'https://api.oxy.tech' or 'http://localhost:3000')
+   */
+  baseUrl: string;
+  /**
+   * API key for authentication (optional for local development)
+   */
+  apiKey?: string;
+  /**
+   * Project ID (UUID)
+   */
+  projectId: string;
+  /**
+   * Optional branch name (defaults to current branch if not specified)
+   */
+  branch?: string;
+  /**
+   * Request timeout in milliseconds (default: 30000)
+   */
+  timeout?: number;
+  /**
+   * Parent window origin for postMessage authentication (iframe scenarios)
+   * Required when using postMessage auth for security.
+   * Example: 'https://app.example.com'
+   * Use '*' only in development!
+   */
+  parentOrigin?: string;
+  /**
+   * Disable automatic postMessage authentication even if in iframe
+   * Set to true if you want to provide API key manually in iframe context
+   */
+  disableAutoAuth?: boolean;
+}
+//#endregion
+//#region src/metricTree.d.ts
+type EdgeKind = "component" | "driver";
+type DriverDirection = "positive" | "negative" | "unknown";
+type DriverStrength = "strong" | "moderate" | "weak";
+type DriverConfidence = "high" | "medium" | "low";
+type DriverForm = "linear" | "log-log" | "log-linear" | "linear-log";
+interface MetricNode {
+  id: string;
+  view: string;
+  measure: string;
+  label: string;
+  description?: string | null;
+  measure_type: string;
+  is_composite: boolean;
+  expr?: string | null;
+}
+interface MetricEdge {
+  from: string;
+  to: string;
+  kind: EdgeKind;
+  /** Sign of a component edge; omitted (defaults to +1) for most edges. */
+  sign?: number;
+  direction: DriverDirection;
+  strength: DriverStrength;
+  confidence: DriverConfidence;
+  coefficient?: number | null;
+  form: DriverForm;
+  intercept?: number | null;
+  lag?: number | null;
+  description?: string | null;
+  refs?: string[] | null;
+}
+interface MetricTree {
+  nodes: MetricNode[];
+  edges: MetricEdge[];
+  root?: string | null;
+}
+interface SensitivityDriver {
+  measure: string;
+  path: string[];
+  edge_kind: string;
+  effective_coefficient?: number | null;
+  form?: DriverForm | null;
+  direction: DriverDirection;
+  strength: DriverStrength;
+  lag?: number | null;
+  description?: string | null;
+}
+interface SensitivityResult {
+  target: string;
+  drivers: SensitivityDriver[];
+}
+interface PredictChange {
+  measure: string;
+  delta: number;
+}
+interface PredictImpact {
+  measure: string;
+  estimated_delta: number;
+  confidence: string;
+  path: string[];
+  form: DriverForm;
+  lag?: number | null;
+}
+interface PredictResult {
+  inputs: PredictChange[];
+  impacts: PredictImpact[];
+}
+type SplitKind = {
+  type: "component";
+  child_measure: string;
+} | {
+  type: "dimension";
+  dimension: string;
+  value: string;
+} | {
+  type: "uniform_degradation";
+  dimension: string;
+  num_elements: number;
+} | {
+  type: "cross_cutting";
+  dimension: string;
+  value: string;
+  measures: string[];
+};
+interface ExplainSibling {
+  split: SplitKind;
+  measure: string;
+  delta: number;
+  root_fraction: number;
+}
+interface ExplainNode {
+  split: SplitKind;
+  measure: string;
+  filters: unknown[];
+  delta: number;
+  concentration: number;
+  root_fraction: number;
+  siblings?: ExplainSibling[];
+  dimension_count?: number;
+  children?: ExplainNode[];
+}
+interface DriverAttribution {
+  driver_measure: string;
+  driver_previous: number;
+  driver_current: number;
+  driver_delta: number;
+  coefficient?: number;
+  form: DriverForm;
+  estimated_target_impact?: number;
+  description?: string;
+}
+type ExplainWarning = {
+  type: "simpsons_paradox";
+  dimension: string;
+  aggregate_delta: number;
+  segment_directions: [string, number][];
+} | {
+  type: "opposing_offset";
+  component_a: string;
+  component_b: string;
+  delta_a: number;
+  delta_b: number;
+} | {
+  type: "non_additive_dimension_split";
+  measure: string;
+  measure_type: string;
+  dimension: string;
+};
+interface ExplainConfigOverride {
+  deep?: boolean;
+  max_depth?: number;
+  coverage_threshold?: number;
+}
+interface ExplainRequest {
+  target: string;
+  time_dimension: string;
+  current_period: [string, string];
+  previous_period: [string, string];
+  config?: ExplainConfigOverride;
+}
+interface ExplainResult {
+  target: string;
+  target_delta: number;
+  target_previous: number;
+  target_current: number;
+  time_dimension: string;
+  current_period: [string, string];
+  previous_period: [string, string];
+  nodes: ExplainNode[];
+  coverage: number;
+  driver_attribution?: DriverAttribution[];
+  alternatives?: unknown[];
+  warnings?: ExplainWarning[];
+}
+interface SegmentOpportunity {
+  segment: string;
+  current_value: number;
+  volume: number;
+  benchmark: number;
+  gap: number;
+  /** Match-the-best upside in measure units. */
+  upside: number;
+}
+interface DimensionOpportunity {
+  dimension: string;
+  cardinality: number;
+  /** "best_peer" or "p75". */
+  benchmark_basis: string;
+  total_upside: number;
+  segments: SegmentOpportunity[];
+  other_segments_skipped: number;
+}
+interface SkippedDimension {
+  dimension: string;
+  reason: string;
+}
+interface OpportunityRequest {
+  target: string;
+  time_dimension: string;
+  period: [string, string];
+}
+interface OpportunityResult {
+  target: string;
+  period: [string, string];
+  overall_value: number;
+  /** "value_share" (additive) or "equal" (ratios). */
+  weight_basis: string;
+  dimensions: DimensionOpportunity[];
+  skipped_dimensions: SkippedDimension[];
+  downstream: PredictImpact[];
+}
+/**
+ * Shape of the inner request helper exposed by `OxyClient`. The metric-tree
+ * client reuses it to inherit auth headers, timeout, baseUrl, and project
+ * scoping rather than reimplementing fetch end-to-end.
+ */
+type RequestFn$1 = <T>(endpoint: string, options?: RequestInit) => Promise<T>;
+/**
+ * Client for the `/semantic/metric-tree*` endpoints. Surfaces the four
+ * airlayer metric-tree analyses (tree introspection, sensitivity, predict,
+ * explain, opportunity) over typed methods.
+ *
+ * Construction is internal to {@link OxyClient} — call `client.metricTree`
+ * to access an instance rather than building one yourself.
+ *
+ * @example
+ * ```typescript
+ * const client = await OxyClient.create({ projectId: "...", apiKey: "..." });
+ * const tree = await client.metricTree.getTree();
+ * const drivers = await client.metricTree.getSensitivity("orders.net_revenue");
+ * ```
+ */
+declare class MetricTreeClient {
+  private readonly request;
+  private readonly config;
+  constructor(config: OxyConfig, request: RequestFn$1);
+  private path;
+  private buildQuery;
+  /**
+   * Fetch the full metric tree, or the subtree rooted at `root`.
+   *
+   * @param root - Optional fully-qualified measure id to root the tree at.
+   * @returns Nodes (measures) and edges (component / driver relationships).
+   *
+   * @example
+   * ```typescript
+   * const tree = await client.metricTree.getTree();
+   * const subtree = await client.metricTree.getTree("orders.net_revenue");
+   * ```
+   */
+  getTree(root?: string): Promise<MetricTree>;
+  /**
+   * Rank the declared drivers of a measure by influence.
+   *
+   * @param measureId - Fully-qualified measure id (`view.measure`).
+   *
+   * @example
+   * ```typescript
+   * const sensitivity = await client.metricTree.getSensitivity("orders.net_revenue");
+   * for (const driver of sensitivity.drivers) {
+   *   console.log(driver.measure, driver.direction, driver.strength);
+   * }
+   * ```
+   */
+  getSensitivity(measureId: string): Promise<SensitivityResult>;
+  /**
+   * Propagate hypothetical `(measure, delta)` changes upward through the
+   * tree. Returns the estimated impact on every downstream measure.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.metricTree.predict([
+   *   { measure: "marketing_spend.total_spend", delta: 10000 },
+   * ]);
+   * ```
+   */
+  predict(changes: PredictChange[]): Promise<PredictResult>;
+  /**
+   * Period-over-period root-cause decomposition. Recursively splits the
+   * target measure by components and dimensions until the move concentrates.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.metricTree.explain({
+   *   target: "financials.operating_profit",
+   *   time_dimension: "financials.month",
+   *   current_period: ["2025-09-01", "2025-09-30"],
+   *   previous_period: ["2025-08-01", "2025-08-31"],
+   * });
+   * ```
+   */
+  explain(request: ExplainRequest): Promise<ExplainResult>;
+  /**
+   * Size the upside opportunity for a measure by finding underperforming
+   * segments. Skips high-cardinality dimensions and trims the long tail.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.metricTree.findOpportunities({
+   *   target: "orders.net_revenue",
+   *   time_dimension: "orders.order_date",
+   *   period: ["2025-09-01", "2025-09-30"],
+   * });
+   * for (const dim of result.dimensions) {
+   *   console.log(dim.dimension, "+", dim.total_upside);
+   * }
+   * ```
+   */
+  findOpportunities(request: OpportunityRequest): Promise<OpportunityResult>;
+}
+//#endregion
+//#region src/anomalies.d.ts
+type AnomalyStatus = "new" | "acknowledged" | "dismissed";
+type AnomalySeverity = "low" | "medium" | "high";
+/**
+ * One row in the anomaly inbox. Detected by `oxy-metric-monitoring` per
+ * `.monitor.yml` entry; upserted by repeat scans so unresolved anomalies
+ * stay visible without piling up duplicates.
+ */
+interface Anomaly {
+  id: string;
+  workspace_id: string;
+  measure: string;
+  time_dimension: string;
+  granularity: string;
+  period_start: string;
+  period_end: string;
+  observed: number;
+  expected: number;
+  lower_bound: number;
+  upper_bound: number;
+  z_score: number;
+  severity: AnomalySeverity | string;
+  status: AnomalyStatus | string;
+  label?: string | null;
+  /** Cached ExplainResult — populated by `POST /anomalies/:id/explain`. */
+  explain_cache?: ExplainResult | null;
+  explain_cached_at?: string | null;
+  detected_at: string;
+  updated_at: string;
+}
+interface ListAnomaliesOptions {
+  status?: AnomalyStatus | string;
+  /** Max rows (server caps at 500, defaults to 100). */
+  limit?: number;
+}
+interface ListAnomaliesResponse {
+  anomalies: Anomaly[];
+}
+interface ScanOptions {
+  /** Override the reference "now" date (YYYY-MM-DD) — useful for demos. */
+  as_of?: string;
+}
+interface ScanResponse {
+  monitors_scanned: number;
+  monitors_failed: number;
+  anomalies_persisted: number;
+}
+type RequestFn = <T>(endpoint: string, options?: RequestInit) => Promise<T>;
+/**
+ * Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`
+ * rather than instantiating directly — the getter wires the request helper
+ * so auth, timeout, and branch propagation come along for free.
+ *
+ * @example
+ * ```typescript
+ * const { anomalies } = await client.anomalies.list({ status: "new" });
+ * for (const a of anomalies) {
+ *   console.log(a.label ?? a.measure, a.severity, a.z_score.toFixed(2));
+ * }
+ * ```
+ */
+declare class AnomaliesClient {
+  private readonly request;
+  private readonly config;
+  constructor(config: OxyConfig, request: RequestFn);
+  private path;
+  private buildQuery;
+  /**
+   * List anomalies in the inbox, newest first.
+   *
+   * @example
+   * ```typescript
+   * // Open / unresolved anomalies only
+   * const { anomalies } = await client.anomalies.list({ status: "new" });
+   * ```
+   */
+  list(options?: ListAnomaliesOptions): Promise<ListAnomaliesResponse>;
+  /**
+   * Trigger a full scan. Iterates every `.monitor.yml` entry in the
+   * workspace, runs the detector, and upserts matching rows into the
+   * inbox. Returns counts of scanned / failed / persisted.
+   *
+   * @example
+   * ```typescript
+   * // Scan against a known-good reference date (matches the seed dataset)
+   * const result = await client.anomalies.scan({ as_of: "2025-12-15" });
+   * console.log(`${result.anomalies_persisted} anomalies detected`);
+   * ```
+   */
+  scan(options?: ScanOptions): Promise<ScanResponse>;
+  /**
+   * Update an anomaly's status (acknowledge / dismiss / re-open).
+   */
+  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.
+   */
+  explain(anomalyId: string): Promise<ExplainResult>;
+}
+//#endregion
 //#region src/customer-app/manifest.d.ts
+/**
+ * Declaration of a single Oxy Function shipped in the bundle's
+ * `functions/` dir. See `internal-docs/2026-06-12-customer-apps-functions-design.md`.
+ *
+ * All fields optional except that at least one invocation surface
+ * (`route`, `schedule`, or `airwayStep`) must be active. Absent =
+ * `route: true` (HTTP-invocable via `useFunction`).
+ */
+interface OxyAppFunctionManifest {
+  /** Source entry, relative to the app dir. Default: `functions/<name>.ts`. */
+  entry?: string;
+  /** Cron expression. When set, the function fires on this schedule. */
+  schedule?: string;
+  /** IANA timezone for `schedule`. Default: `UTC`. */
+  timezone?: string;
+  /** Expose `POST .../fn/<name>` (called via `useFunction`). Default: true. */
+  route?: boolean;
+  /** Wire the function in as an Airway pipeline transform step. */
+  airwayStep?: {
+    pipeline: string;
+    resource: string;
+  };
+  /** Wall-clock timeout. Default 30, max 300. */
+  timeoutSeconds?: number;
+  /**
+   * Opt-in result caching for route invocations. Omit (the default) to never
+   * cache — the safe choice for a side-effectful function (writes, external
+   * POSTs, ELT). Set `ttlSeconds` ONLY for read-only / idempotent functions:
+   * results are then cached per (build, function, user, request body) for that
+   * window, and a repeat `useFunction().invoke(sameBody)` returns the cached
+   * result without re-running. A `?refresh` query bypasses it.
+   */
+  cache?: {
+    ttlSeconds?: number;
+  };
+  /**
+   * Databases this function's `ctx.warehouse.*` writes may target. Omit (or
+   * leave empty) and the function may NOT write to any database — writes are
+   * fail-closed and rejected before any connection is opened. Declare a
+   * destination here ONLY for a function that legitimately writes to it; a
+   * read-only function omits it. This scopes writes away from the project's
+   * source warehouse.
+   */
+  destinations?: string[];
+  /**
+   * Capability to write app-scoped secrets via `ctx.secrets.set` (fail-closed:
+   * omit → writes rejected). Only the app's own `apps/<app-id>/` namespace is
+   * writable. Declare for a function that persists state — e.g. a scheduled
+   * token-refresher that writes the rotated token back to Oxy Secrets.
+   */
+  secrets?: {
+    write?: boolean;
+  };
+  /**
+   * Capability to send email via `ctx.email.send` (fail-closed: omit → the
+   * host rejects `ctx.email.send` before any provider call). Declare for a
+   * function that emails the app's users — e.g. a `notify` route that sends a
+   * welcome message, or a scheduled digest. The sender mailbox is
+   * platform-controlled; a function may set `replyTo` but never `from`.
+   */
+  email?: {
+    send?: boolean;
+  };
+  /**
+   * Retry policy for **background** runs (a `schedule` fire or a manual job
+   * trigger). Omit → a job run is attempted once. Route (HTTP) invocations are
+   * request-scoped and never retried. `maxAttempts` counts the first try
+   * (`maxAttempts: 3` = up to 2 retries); backoff is exponential (doubling)
+   * between `minTimeoutMs` and `maxTimeoutMs`. Maps to the durable queue's
+   * retry policy — a transient failure re-runs the whole isolate.
+   */
+  retries?: {
+    maxAttempts?: number;
+    minTimeoutMs?: number;
+    maxTimeoutMs?: number;
+  };
+  /**
+   * Example input params for the function — a sample JSON body the admin "Run
+   * now" surface prefills so an operator knows what to pass (the function reads
+   * it as its `req` body, same as a route invocation). Advisory only; not
+   * enforced at runtime.
+   */
+  inputExample?: unknown;
+}
 /** Wire shape of `oxy-app.json` (v2 only). */
 interface OxyAppManifest {
   /** Must be 2. v1 manifests are no longer supported. */
@@ -31,6 +546,12 @@ interface OxyAppManifest {
    * `/api/projects/:id/query` URL.
    */
   projectId?: string;
+  /**
+   * Optional map of Oxy Functions (server-side handlers) shipped in the
+   * bundle's `functions/` dir, keyed by function name. Omit for a pure
+   * static bundle (today's default). See the functions design doc.
+   */
+  functions?: Record<string, OxyAppFunctionManifest>;
 }
 /**
  * Manifest + runtime-injected identity needed to call oxy. Callers
@@ -119,6 +640,30 @@ interface CustomerAppDebugSnapshot {
 declare function getCustomerAppDebug(resolved: ResolvedCustomerAppManifest): Promise<CustomerAppDebugSnapshot>;
 //#endregion
 //#region src/customer-app/errors.d.ts
+/**
+ * Error thrown by all customer-app hooks when an API call returns a
+ * non-2xx response. Carries the structured `code` + `hint` the server
+ * emits so bundle UIs can render an actionable message instead of
+ * "404: { ...json... }".
+ */
+declare class OxyApiError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+  readonly hint: string | null;
+  constructor(opts: {
+    status: number;
+    message: string;
+    code?: string | null;
+    hint?: string | null;
+  });
+}
+/**
+ * Read a non-2xx response from oxy and return an `OxyApiError`.
+ * Parses the JSON envelope when present; falls back to raw text
+ * (truncated to 240 chars so a runaway HTML error page doesn't
+ * dominate the bundle UI).
+ */
+declare function apiErrorFromResponse(resp: Response): Promise<OxyApiError>;
 interface CustomerAppErrorReport {
   title: string;
   message: string;
@@ -128,6 +673,118 @@ interface CustomerAppErrorReport {
 /** Interpret a thrown error as a structured report for UI display. */
 declare function interpretCustomerAppError(err: unknown): CustomerAppErrorReport;
 //#endregion
+//#region src/customer-app/function-context.d.ts
+/**
+ * The request passed as the first argument to a function's default export.
+ *
+ * The host hands the isolate the raw request body as a string (see
+ * `req_json` in `runtime.rs`); parse it yourself, e.g.
+ * `JSON.parse(req.body || "{}")`. This is intentionally *not* a full Web
+ * `Request` — there is no `.json()` / headers object in v1.
+ */
+interface OxyFunctionRequest {
+  /** Raw request body as received (JSON string for a JSON POST). */
+  body: string;
+}
+/** A single row from a `ctx.query` / `ctx.queryStream` result. */
+type OxyFunctionRow = Record<string, unknown>;
+/** Identity of the invoking user (route) or the system identity (schedule/airway). */
+interface OxyFunctionUser {
+  id: string;
+  email: string;
+  orgId: string;
+}
+/** Result of a `ctx.fetch` call. */
+interface OxyFetchResult {
+  status: number;
+  body: string;
+}
+/** `ctx.warehouse.*` — writes to one of the app's configured destination databases. */
+interface OxyWarehouseApi {
+  insert(database: string, table: string, rows: OxyFunctionRow[]): Promise<unknown>;
+  exec(database: string, sql: string): Promise<unknown>;
+  upsert(database: string, table: string, rows: OxyFunctionRow[], conflictColumns: string[]): Promise<unknown>;
+}
+/** `ctx.secrets` — write app-scoped secrets (gated by the `secrets.write` capability). */
+interface OxySecretsApi {
+  set(key: string, value: string): Promise<void>;
+}
+/** `ctx.semantic` — airlayer-compiled semantic queries (inherits the pre-agg fast path). */
+interface OxySemanticApi {
+  query(spec: Record<string, unknown>): Promise<unknown>;
+}
+/** `ctx.airway` — seed/await an Airway ELT pipeline run. */
+interface OxyAirwayApi {
+  run(pipelineRef: string, variables?: Record<string, unknown> | null): Promise<{
+    runId: string;
+  }>;
+}
+/**
+ * Input to `ctx.email.send`. Platform-injected: the sender mailbox (`from`) is
+ * platform-controlled and **not** an accepted field — passing it is a typed
+ * error. Provide `html` and/or `text` as the body (render a template to HTML
+ * with `render` from `@oxy-hq/sdk/email`).
+ */
+interface EmailSendInput {
+  /** Recipient address(es). Required. */
+  to: string | string[];
+  /** CC address(es). */
+  cc?: string | string[];
+  /** BCC address(es). */
+  bcc?: string | string[];
+  /** Reply-To address — the only sender-identity field an author may set. */
+  replyTo?: string;
+  /** Subject line. Required. */
+  subject: string;
+  /** HTML body. Provide at least one of `html` / `text`. */
+  html?: string;
+  /** Plain-text body. Provide at least one of `html` / `text`. */
+  text?: string;
+  /**
+   * Optional idempotency key (≤256 chars). Accepted and validated in v1 but a
+   * no-op until the persisted idempotency table lands — adopt it now so
+   * background (retried) sends become exactly-once once it does.
+   */
+  idempotencyKey?: string;
+}
+/** Result of a successful `ctx.email.send`. */
+interface EmailSendResult {
+  /** Provider (SES) message id of the sent message. */
+  messageId: string;
+}
+/** `ctx.email` — send email (gated by the `email.send` capability). */
+interface OxyEmailApi {
+  send(input: EmailSendInput): Promise<EmailSendResult>;
+}
+/**
+ * The data-plane context passed as the second argument to a function's default
+ * export. Mirrors the host-assembled `ctx` (`__buildCtx` in `runtime.rs`);
+ * every member is a host-provided async function bridged to a Rust backend.
+ */
+interface OxyFunctionContext {
+  /** Invoking user (route) or system identity (schedule/airway). */
+  user: OxyFunctionUser;
+  /** Read-only view of the app's configured secrets (project-scoped). */
+  env: Record<string, string>;
+  /** Structured per-invocation logging (captured + surfaced with the response). */
+  log(...args: unknown[]): void;
+  /** Read-only SQL (SELECT/WITH only), function-scoped row cap. Resolves to the rows. */
+  query(sql: string): Promise<OxyFunctionRow[]>;
+  /** Read-only SQL with a higher row cap, yielded to the caller in batches. */
+  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>;
+  warehouse: OxyWarehouseApi;
+  secrets: OxySecretsApi;
+  semantic: OxySemanticApi;
+  airway: OxyAirwayApi;
+  email: OxyEmailApi;
+}
+/** 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
 /**
  * Shape of `window.__OXY_APP__` written by oxy at serve time.
@@ -167,6 +824,13 @@ declare function setOxyAppLogger(logger: OxyAppLogger | null): void;
 /** Used by the SDK internals; not part of the public surface. */
 declare function getOxyAppLogger(): OxyAppLogger;
 //#endregion
+//#region src/customer-app/function-sse.d.ts
+/** A captured `console.*` / `ctx.log` line from a function run. */
+interface FunctionLog {
+  level: string;
+  message: string;
+}
+//#endregion
 //#region src/customer-app/react.d.ts
 /**
  * Credentialed fetch wrapper stored in context so `useQuery` can share
@@ -206,29 +870,6 @@ interface OxyAppProviderProps {
  * render after the manifest is ready (or the error fallback fires).
  */
 declare function OxyAppProvider(props: OxyAppProviderProps): React.JSX.Element;
-/**
- * Error thrown by all customer-app hooks when an API call returns a
- * non-2xx response. Carries the structured `code` + `hint` the server
- * emits so bundle UIs can render an actionable message instead of
- * "404: { ...json... }".
- *
- * The server contract is documented in
- * `crates/app/src/server/api/projects/agent_ask.rs` and
- * `procedure_run.rs` — both emit `{ message, code?, hint? }` as JSON.
- * Hooks that previously wrapped the raw text in `new Error()` now
- * throw this type instead.
- */
-declare class OxyApiError extends Error {
-  readonly status: number;
-  readonly code: string | null;
-  readonly hint: string | null;
-  constructor(opts: {
-    status: number;
-    message: string;
-    code?: string | null;
-    hint?: string | null;
-  });
-}
 /**
  * Read the resolved manifest from context. Throws if called outside
  * `<OxyAppProvider>` — that's a programmer error worth surfacing
@@ -261,6 +902,42 @@ interface UseQueryResult<Row = Record<string, unknown>> {
  * available (e.g. a user-supplied filter value).
  */
 declare function useQuery<Row = Record<string, unknown>>(input: UseQueryInput, opts?: UseQueryOpts): UseQueryResult<Row>;
+interface UseFunctionResult<Data = unknown> {
+  /**
+   * Invoke the function with an optional JSON body. Resolves to the parsed
+   * result. Pass `{ idempotencyKey }` to make a side-effectful invocation
+   * exactly-once: a retry with the same key replays the stored result instead
+   * of re-executing. Send a fresh key per logical action (e.g. a UUID per
+   * journal entry).
+   */
+  invoke: (body?: unknown, opts?: {
+    idempotencyKey?: string;
+  }) => Promise<Data>;
+  /** Last successful result, or null before the first invoke. */
+  data: Data | null;
+  /** True while an invocation is in flight. */
+  isLoading: boolean;
+  /** Last invocation error, or null. On error this carries `.logs` too. */
+  error: Error | null;
+  /**
+   * `console.*` / `ctx.log` output from the last invoke (success or error), so
+   * a developer can see what the function printed without opening the oxy
+   * server logs. Empty for a cache hit or idempotent replay — no run happened,
+   * so there is nothing to log.
+   */
+  logs: FunctionLog[];
+}
+/**
+ * Imperative hook for invoking an Oxy Function by name.
+ *
+ * ```tsx
+ * const refresh = useFunction("refresh-sales");
+ * <button disabled={refresh.isLoading} onClick={() => refresh.invoke({ full: true })}>
+ *   Refresh
+ * </button>
+ * ```
+ */
+declare function useFunction<Data = unknown>(name: string): UseFunctionResult<Data>;
 /** Scalar filter operators (compared against a single value). */
 type SemanticScalarOp = "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
 /** Array filter operators (compared against a list). */
@@ -457,6 +1134,35 @@ interface UseAgentRunResult {
   error: Error | null;
 }
 declare function useAgentRun(input: UseAgentRunInput): UseAgentRunResult;
+/**
+ * Engineer-tagged usage event. Free-form `event_name` (≤ 64 chars,
+ * `[a-z][a-z0-9-]*` validated server-side) + optional JSON `payload`
+ * (object, ≤ 4 KiB serialized). Surfaces in the admin Activity tab
+ * grouped by name, with drill-down into recent occurrences.
+ *
+ * The handler returned by [`useTrackEvent`] is **fire-and-forget**:
+ * it enqueues the event into an in-memory batch flushed every second
+ * (and on `pagehide` so a navigation away doesn't drop the tail).
+ * No await semantics — call it inline from a click handler without
+ * awaiting it. Server-side validation errors are logged to the
+ * console; the call site doesn't need to handle them.
+ *
+ * Example:
+ * ```tsx
+ * const track = useTrackEvent();
+ * <button
+ *   onClick={() => {
+ *     track("export-clicked", { format: "csv", rowCount });
+ *     doExport();
+ *   }}
+ * >Export</button>
+ * ```
+ *
+ * Rate-limited at 60/min per (user, app) on the server. A burst that
+ * trips the limit drops the excess events with a console warning;
+ * within-limit events are unaffected.
+ */
+declare function useTrackEvent(): (name: string, payload?: Record<string, unknown>) => void;
 interface OxyAnswerProps {
   /** Markdown answer text from `useAgentRun().answer`. */
   answer: string | null;
@@ -530,5 +1236,5 @@ interface OxyChatProps {
  */
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
-export { type AgentArtifact, type AgentRunEvent, type AgentRunState, type AgentSqlArtifact, type AppFetcher, type CustomerAppDebugSnapshot, type CustomerAppErrorReport, type LoadManifestOptions, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyInjectedAppConfig, type ProcedureProgress, type ProcedureResult, type ProcedureRunState, type ResolvedCustomerAppManifest, type SemanticArrayOp, type SemanticDateRangeOp, type SemanticFilter, type SemanticScalarOp, type SemanticTimeDimension, type UseAgentRunInput, type UseAgentRunResult, type UseProcedureRunInput, type UseProcedureRunOpts, type UseProcedureRunResult, type UseQueryInput, type UseQueryOpts, type UseQueryResult, type UseSemanticQueryInput, type UseSemanticQueryOpts, type UseSemanticQueryResult, _resetCustomerAppManifestCacheForTest, getCustomerAppDebug, getOxyAppLogger, interpretCustomerAppError, loadCustomerAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery };
+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, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
 //# sourceMappingURL=index.d.cts.map