@oxy-hq/sdk 2.3.0 → 2.5.0

package/dist/react-BnpR8VRJ.d.mts

@@ -0,0 +1,656 @@
+
+import * as React from "react";
+//#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. */
+  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>;
+  /**
+   * Optional Ask Oxygen binding (agent ref + composer chips). The
+   * platform's registered copy is authoritative (surfaced by
+   * shell-context); this local copy is the dev-time fallback so the
+   * shell's Ask dock works before the app is registered.
+   */
+  ask?: {
+    agent?: string;
+    suggestedQuestions?: string[];
+  };
+}
+/**
+ * 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/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;
+  hint: string;
+  docs?: string;
+}
+/** Interpret a thrown error as a structured report for UI display. */
+declare function interpretCustomerAppError(err: unknown): CustomerAppErrorReport;
+//#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;
+  /**
+   * Origin of the oxy backend to call (e.g. `https://oxy.example.com` or
+   * `http://localhost:3000`). When set, the SDK resolves its relative `/api/…`
+   * requests — `shell-context`, Ask Oxygen, events — against this origin
+   * instead of the app's own, so a standalone / cross-origin dev app can drive
+   * the wired shell without a same-origin proxy. The backend must allow the
+   * app's origin (see oxy's dev-origin CORS list). Leave unset when the app is
+   * served same-origin by oxy.
+   */
+  backendUrl?: string;
+  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;
+/**
+ * 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;
+/**
+ * Low-level hook that returns the raw context value (including the
+ * fetcher). Prefer `useResolvedManifest` for manifest access; use
+ * this only when you need the fetcher or identity without requiring
+ * the manifest to be ready (e.g. inside `useQuery`, or the shell
+ * chrome, which must never block the app on the manifest load).
+ */
+declare function useOxyApp(): {
+  projectId: string | undefined;
+  appSlug: string | undefined;
+  orgSlug: string | undefined;
+  fetcher: AppFetcher;
+};
+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 { UseSemanticQueryOpts as A, CustomerAppErrorReport as B, UseProcedureRunInput as C, UseQueryOpts as D, UseQueryInput as E, useProcedureRun as F, OxyAppFunctionManifest as G, apiErrorFromResponse as H, useQuery as I, _resetCustomerAppManifestCacheForTest as J, OxyAppManifest as K, useResolvedManifest as L, useAgentRun as M, useFunction as N, UseQueryResult as O, useOxyApp as P, useSemanticQuery as R, UseFunctionResult as S, UseProcedureRunResult as T, interpretCustomerAppError as U, OxyApiError as V, LoadManifestOptions as W, loadCustomerAppManifest as Y, SemanticFilter as _, AppFetcher as a, UseAgentRunInput as b, OxyAppProvider as c, OxyChatProps as d, ProcedureProgress as f, SemanticDateRangeOp as g, SemanticArrayOp as h, AgentSqlArtifact as i, UseSemanticQueryResult as j, UseSemanticQueryInput as k, OxyAppProviderProps as l, ProcedureRunState as m, AgentRunEvent as n, OxyAnswer as o, ProcedureResult as p, ResolvedCustomerAppManifest as q, AgentRunState as r, OxyAnswerProps as s, AgentArtifact as t, OxyChat as u, SemanticScalarOp as v, UseProcedureRunOpts as w, UseAgentRunResult as x, SemanticTimeDimension as y, useTrackEvent as z };
+//# sourceMappingURL=react-BnpR8VRJ.d.mts.map

package/dist/react-BnpR8VRJ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-BnpR8VRJ.d.mts","names":[],"sources":["../src/customer-app/manifest.ts","../src/customer-app/errors.ts","../src/customer-app/function-sse.ts","../src/customer-app/react.tsx"],"mappings":"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"}