@oxy-hq/sdk 2.1.0 → 2.4.0

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 
-import * as React from "react";
-
+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";
 //#region src/config.d.ts
 /**
  * Configuration for the Oxy SDK
@@ -433,140 +432,6 @@ declare class AnomaliesClient {
   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[];
-}
-/** Wire shape of `oxy-app.json` (v2 only). */
-interface OxyAppManifest {
-  /** Must be 2. v1 manifests are no longer supported. */
-  schemaVersion: 2;
-  /**
-   * Optional display name. The admin "Link existing" dialog prefills
-   * its Name field from this. Omit to let oxy fall back to the
-   * folder basename.
-   */
-  name?: string;
-  /**
-   * URL slug. **Required.** The canonical source of truth — the
-   * dialog locks the slug field to this value, and
-   * `OXY_APP_BASE_PATH=/customer-apps/<org>/<slug>/` baked into the
-   * build must match.
-   */
-  slug: string;
-  /**
-   * Optional org slug. Prefills the dialog's org picker; operator
-   * can still override. Carries no security weight — the actual
-   * access check is on the linked row.
-   */
-  orgSlug?: string;
-  /**
-   * Optional project (workspace) uuid the bundle expects to read
-   * from. Used by `useQuery` to construct the
-   * `/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
- * should treat this as the only source of truth for "which org/app
- * does this bundle belong to."
- */
-interface ResolvedCustomerAppManifest {
-  manifest: OxyAppManifest;
-  /**
-   * Always an empty array for v2 manifests. Kept for API compatibility;
-   * callers that previously iterated product names should switch to
-   * explicit `useQuery` calls.
-   * @deprecated Will be removed in a future version.
-   */
-  productNames: string[];
-  /** Org slug injected by oxy. */
-  orgSlug: string;
-  /** App slug injected by oxy. */
-  appSlug: string;
-  /**
-   * The oxy server's API base URL. Empty string when oxy serves the
-   * bundle itself (same-origin, the common case); a full URL only
-   * when the bundle is running under a dev server proxy.
-   */
-  apiBaseUrl: string;
-  /** App UUID; informational. */
-  appId?: string;
-  /**
-   * Project (workspace) UUID. Injection (`window.__OXY_APP__.projectId`)
-   * wins over the manifest's `projectId` field — the admin row is
-   * authoritative. Manifest `projectId` is a dev-time hint used only
-   * when running without a server. Used by `useQuery` to construct the
-   * `/api/projects/:id/query` URL.
-   */
-  projectId?: string;
-}
-interface LoadManifestOptions {
-  /**
-   * Override the URL the manifest is fetched from. Default:
-   * `<injected_base>/oxy-app.json` or `/oxy-app.json`.
-   * Useful for non-Next bundlers — set explicitly to wherever your
-   * bundler emits static assets.
-   */
-  manifestUrl?: string;
-}
-/**
- * Load + validate the manifest. Cached after the first call so callers
- * can invoke this from every component without coordinating.
- */
-declare function loadCustomerAppManifest(options?: LoadManifestOptions): Promise<ResolvedCustomerAppManifest>;
-/** For tests: reset the cache between runs. */
-declare function _resetCustomerAppManifestCacheForTest(): void;
-//#endregion
 //#region src/customer-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
@@ -601,15 +466,117 @@ interface CustomerAppDebugSnapshot {
  */
 declare function getCustomerAppDebug(resolved: ResolvedCustomerAppManifest): Promise<CustomerAppDebugSnapshot>;
 //#endregion
-//#region src/customer-app/errors.d.ts
-interface CustomerAppErrorReport {
-  title: string;
-  message: string;
-  hint: string;
-  docs?: string;
+//#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;
 }
-/** Interpret a thrown error as a structured report for UI display. */
-declare function interpretCustomerAppError(err: unknown): CustomerAppErrorReport;
+/** 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
 /**
@@ -650,440 +617,5 @@ 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
- * the same request mechanism without coupling it to the global `fetch`.
- *
- * Sends `credentials: "include"` so the session cookie rides along when
- * the app is served by oxy (in-workspace / admin preview) — that cookie
- * authorizes data calls. For local dev (cross-origin), the
- * `@oxy-hq/vite-plugin` proxy attaches the developer's token. Bundles may
- * override the fetcher for test/proxy environments.
- */
-type AppFetcher = typeof fetch;
-interface OxyAppProviderProps {
-  /** Optional manifest load options. Same shape as `loadCustomerAppManifest`. */
-  manifestOptions?: LoadManifestOptions;
-  /**
-   * Rendered while the manifest is loading. Defaults to nothing; pass a
-   * spinner if you want one.
-   */
-  fallback?: React.ReactNode;
-  /**
-   * Rendered on manifest load failure. Receives the structured error
-   * report so the bundle can show its own branded error card. Defaults
-   * to a minimal text-only fallback (better than a blank page).
-   */
-  errorFallback?: (err: CustomerAppErrorReport) => React.ReactNode;
-  /**
-   * Override the fetch implementation used by all hooks (`useQuery`).
-   * Useful for test environments or proxy setups. Defaults to a wrapper
-   * that sets `credentials: "include"` on every request.
-   */
-  fetcher?: AppFetcher;
-  children: React.ReactNode;
-}
-/**
- * Top-level provider. Loads the manifest once on mount; children only
- * 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
- * loudly, not silently swallowing.
- */
-declare function useResolvedManifest(): ResolvedCustomerAppManifest;
-interface UseQueryInput {
-  sql: string;
-  database?: string;
-}
-interface UseQueryOpts {
-  params?: Record<string, string | number | boolean | null | undefined>;
-  /** Set false to skip the request (e.g., waiting on user input). */
-  enabled?: boolean;
-}
-interface UseQueryResult<Row = Record<string, unknown>> {
-  rows: Row[];
-  columns: string[];
-  loading: boolean;
-  error: Error | null;
-  refetch: () => void;
-}
-/**
- * Execute an ad-hoc SQL query against the project linked to this
- * customer app. The query is specified inline by the caller; no
- * manifest declaration is involved.
- *
- * Re-runs whenever `input` or enabled `params` change. Use the
- * `enabled` option to defer the first fetch until required data is
- * 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). */
-type SemanticArrayOp = "in" | "not_in";
-/** Date-range filter operators. `from` / `to` accept ISO date strings. */
-type SemanticDateRangeOp = "in_date_range" | "not_in_date_range";
-/**
- * One filter clause. The `field` references a dimension name within
- * the topic; the `op` discriminator picks which other fields are
- * meaningful. Wire shape matches `agentic_semantic::SemanticFilter`
- * verbatim — the bundle's request body is forwarded to airlayer's
- * compiler with no translation.
- */
-type SemanticFilter = {
-  field: string;
-  op: SemanticScalarOp;
-  value: string | number | boolean | null;
-} | {
-  field: string;
-  op: SemanticArrayOp;
-  values: Array<string | number | boolean | null>;
-} | {
-  field: string;
-  op: SemanticDateRangeOp;
-  from: string;
-  to: string;
-};
-/** Time dimensions with optional granularity (e.g. "day", "month"). */
-interface SemanticTimeDimension {
-  dimension: string;
-  granularity?: "day" | "week" | "month" | "quarter" | "year";
-}
-interface UseSemanticQueryInput {
-  topic: string;
-  dimensions?: string[];
-  measures?: string[];
-  time_dimensions?: SemanticTimeDimension[];
-  filters?: SemanticFilter[];
-  limit?: number;
-}
-interface UseSemanticQueryOpts {
-  /** Set false to skip the request (e.g., waiting on user input). */
-  enabled?: boolean;
-  /**
-   * When true, the response includes the compiled SQL string at
-   * `sql`. Off by default — production callers shouldn't bake the
-   * warehouse SQL into their UI. Bundle authors flip this on while
-   * debugging.
-   */
-  debug?: boolean;
-}
-interface UseSemanticQueryResult<Row = Record<string, unknown>> {
-  rows: Row[];
-  columns: string[];
-  /** True when the result was capped at the server's row limit. */
-  truncated: boolean;
-  /** Compiled SQL — populated only when `opts.debug` is true. */
-  sql: string | null;
-  loading: boolean;
-  error: Error | null;
-  refetch: () => void;
-}
-/**
- * Run a semantic-layer query against the project's `.view.yml` /
- * `.topic.yml` definitions. The server compiles to SQL and executes
- * through the same connector path as `useQuery`, so result shape
- * matches.
- *
- * Re-runs whenever the input shape changes (deep-compared via JSON).
- * Use `opts.enabled = false` to defer the first fetch until required
- * inputs (e.g. a user-picked filter value) are available.
- */
-declare function useSemanticQuery<Row = Record<string, unknown>>(input: UseSemanticQueryInput, opts?: UseSemanticQueryOpts): UseSemanticQueryResult<Row>;
-type ProcedureRunState = "idle" | "running" | "done" | "failed";
-interface UseProcedureRunInput {
-  procedureId: string;
-}
-interface UseProcedureRunOpts {
-  /** Polling cadence in ms while running. Default: 2000 (procedures
-   *  are typically minutes-long; tighter cadence wastes resources). */
-  pollIntervalMs?: number;
-  pollIntervalBackoffMs?: number;
-  /** Max client-side wait in ms. Default: 1 hour. */
-  maxWaitMs?: number;
-}
-interface ProcedureProgress {
-  step: string;
-  percent: number;
-}
-interface ProcedureResult {
-  summary: string;
-  outputs: Record<string, unknown>;
-}
-interface UseProcedureRunResult {
-  state: ProcedureRunState;
-  run: (params?: Record<string, unknown>) => void;
-  /** Cancel the in-flight run. Idempotent. */
-  cancel: () => void;
-  progress: ProcedureProgress | null;
-  result: ProcedureResult | null;
-  error: Error | null;
-}
-/**
- * @beta Long-running procedure runner. The wire shape works end-to-end
- * (start → poll → cancel; runs survive server restarts via the
- * `customer_app_procedure_runs` table) but a few rough edges remain
- * before this is GA-ready:
- *
- *   - Hint surfaces for `procedure_not_found` are correct but the
- *     procedure-discovery rules (which directories the server scans,
- *     case-sensitivity, branch awareness) aren't documented yet.
- *   - Cancellation across multi-instance deployments leans on a
- *     periodic sweep — fine for now, but expect occasional latency
- *     between `cancel()` and the run actually stopping.
- *   - Progress reporting requires the procedure to emit named
- *     steps; bundles get `progress: null` until that lands.
- *
- * The API surface is stable; expect breaking changes only if the
- * server-side `customer_app_procedure_runs` schema changes.
- */
-declare function useProcedureRun(input: UseProcedureRunInput, opts?: UseProcedureRunOpts): UseProcedureRunResult;
-type AgentRunState = "idle" | "running" | "needs_clarification" | "done" | "failed";
-interface AgentRunEvent {
-  type: string;
-  data: unknown;
-}
-/** SQL produced and (optionally) executed by the agent. Extracted
- *  from `query_generated` / `query_executed` / `verified_sql` /
- *  `semantic_query` / `omni_query` SSE events so callers don't have
- *  to scan the raw event stream themselves. */
-interface AgentSqlArtifact {
-  type: "sql";
-  /** Stable id derived from the SSE event id so React keys stay
-   *  stable across re-renders / reconnects. */
-  id: string;
-  /** Originating UI event type — preserves the verified/semantic/etc.
-   *  flavor in case the renderer wants a badge. */
-  source: string;
-  sql: string;
-  /** Present when the SQL was executed and rows came back. */
-  results?: {
-    columns: string[];
-    rows: unknown[][];
-    rowCount: number;
-  };
-  /** Present when execution failed — surface it so the bundle UI can
-   *  show the failure inline next to the SQL instead of swallowing
-   *  it inside the agent's final answer. */
-  error?: string;
-}
-type AgentArtifact = AgentSqlArtifact;
-interface UseAgentRunInput {
-  agentId: string;
-}
-interface UseAgentRunResult {
-  state: AgentRunState;
-  /** Submit a question and open the SSE stream. */
-  ask: (question: string, opts?: {
-    threadId?: string;
-  }) => void;
-  /** Cancel the in-flight stream + the server-side run. Idempotent. */
-  cancel: () => void;
-  /** Accumulated raw events for advanced consumers. */
-  events: AgentRunEvent[];
-  /** SQL artifacts extracted from the event stream — convenience
-   *  view over `events` so renderers don't have to know which event
-   *  types carry SQL. */
-  artifacts: AgentArtifact[];
-  /** Final answer once a `done` event arrives. Markdown. */
-  answer: string | null;
-  /** Clarification text once a suspension event arrives. */
-  clarification: string | null;
-  /** Thread id used by the active run (stable across follow-ups). */
-  threadId: string | null;
-  /**
-   * @beta Relative path to the full thread view in oxy (e.g.
-   * `/threads/<id>` for local mode, or
-   * `/<org_slug>/workspaces/<ws_id>/threads/<id>` in cloud). Set
-   * once the run starts so a bundle can render a "Continue in Oxy"
-   * link without constructing the URL itself.
-   *
-   * Caveats while in beta:
-   *   - The bundle's origin and the oxy app shell's origin can
-   *     differ in cloud deployments. If they do, this relative URL
-   *     resolves against the bundle's origin and 404s. A future
-   *     release will expose the oxy app origin via the manifest;
-   *     for now, prefix at the call site if you know your
-   *     deployment topology, or hide the link entirely.
-   *   - The thread row may not be queryable until the run produces
-   *     its first event — clicking the link immediately after
-   *     `ask()` can land on a "thread not found" page.
-   */
-  threadUrl: string | null;
-  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;
-  /** SQL artifacts from `useAgentRun().artifacts`. */
-  artifacts?: AgentArtifact[];
-  /** Lifecycle state — drives the placeholder, spinner, error UI. */
-  state: AgentRunState;
-  /** Clarification text when `state === "needs_clarification"`. */
-  clarification?: string | null;
-  /** Failure reason when `state === "failed"`. */
-  error?: Error | null;
-  /**
-   * @beta Relative URL to the thread view in oxy — renders a
-   * "Continue in Oxy (beta)" link when set. Pass `null` to suppress
-   * the link entirely; the link is marked beta because the resolved
-   * URL may not reach a live thread in every deployment topology
-   * (see `UseAgentRunResult.threadUrl`).
-   */
-  threadUrl?: string | null;
-  /** Override the link label. Default: "Continue this thread in Oxy". */
-  threadLinkLabel?: string;
-  /** Maximum number of SQL result rows to render per artifact. Older
-   *  rows truncated with a "+N more" note. Default: 10. */
-  maxArtifactRows?: number;
-  /** Class on the outer container — for callers using utility CSS. */
-  className?: string;
-}
-/**
- * Renders an agent run's answer + artifacts + thread link as a
- * single block. The default styling is intentionally neutral
- * (system fonts, gray surfaces) so it blends into any bundle.
- *
- * Designed to be paired with `useAgentRun`:
- *
- * ```tsx
- * const run = useAgentRun({ agentId: "analyst" });
- * return (
- *   <>
- *     <button onClick={() => run.ask("how many users last week?")}>Ask</button>
- *     <OxyAnswer {...run} />
- *   </>
- * );
- * ```
- */
-declare function OxyAnswer(props: OxyAnswerProps): React.JSX.Element;
-interface OxyChatProps {
-  /** Agent id (matches `<id>.agentic.yml` in the project). */
-  agentId: string;
-  /** Placeholder for the question input. */
-  placeholder?: string;
-  /** Button label. Default: "Ask". */
-  submitLabel?: string;
-  /** Rendered when the user hasn't asked anything yet. */
-  emptyState?: React.ReactNode;
-  /** Forwarded to the inner `<OxyAnswer>`. */
-  maxArtifactRows?: number;
-  /** Class on the outer container. */
-  className?: string;
-}
-/**
- * Complete drop-in chat surface. One agent, one input, one answer
- * view. The chat is single-turn by default — each new question
- * cancels the previous run and clears the answer. Bundles that
- * want a multi-turn conversation history compose their own UI
- * using `useAgentRun` directly.
- *
- * Single-turn keeps the surface dead simple: bundles use this for
- * the "ask anything about your data" widget that sits next to
- * structured panels. Multi-turn is rare in those contexts and
- * better expressed by the bundle.
- */
-declare function OxyChat(props: OxyChatProps): React.JSX.Element;
-//#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 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, OxyAnswer, type OxyAnswerProps, OxyApiError, type OxyAppFunctionManifest, type OxyAppLogLevel, type OxyAppLogger, type OxyAppManifest, OxyAppProvider, type OxyAppProviderProps, OxyChat, type OxyChatProps, type OxyInjectedAppConfig, 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, getCustomerAppDebug, getOxyAppLogger, interpretCustomerAppError, loadCustomerAppManifest, readInjectedAppConfig, setOxyAppLogger, useAgentRun, useFunction, useProcedureRun, useQuery, useResolvedManifest, useSemanticQuery, useTrackEvent };
+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 };
 //# sourceMappingURL=index.d.mts.map