@oxy-hq/sdk 2.3.0 → 2.5.0

package/dist/shell.d.mts

@@ -0,0 +1,346 @@
+
+import { a as AppFetcher, n as AgentRunEvent } from "./react-BnpR8VRJ.mjs";
+import * as React from "react";
+import { ReactNode } from "react";
+//#region src/shell/AnswerChart.d.ts
+interface ChartBlockConfig {
+  chart_type: "line_chart" | "bar_chart" | "pie_chart" | "table";
+  x?: string;
+  y?: string;
+  series?: string;
+  name?: string;
+  value?: string;
+  title?: string;
+  x_axis_label?: string;
+  y_axis_label?: string;
+}
+interface ChartBlock {
+  config: ChartBlockConfig;
+  columns: string[];
+  rows: unknown[][];
+}
+interface AnswerChartProps {
+  block: ChartBlock;
+  className?: string;
+}
+/** Renders one `chart_rendered` block. Uses ECharts (interactive, matching
+ *  the main web-app) when the host app has it installed; otherwise falls
+ *  back to a dependency-free SVG render. Table type always uses SVG. */
+declare function AnswerChart({ block, className }: AnswerChartProps): React.JSX.Element;
+//#endregion
+//#region src/shell/AskDock.d.ts
+interface AskDockProps {
+  /** Agent the panel asks (the app manifest's `ask.agent`). */
+  agentId: string;
+  /** Workspace display name for the composer placeholder. */
+  workspaceName?: string;
+  /** Suggested-question chips shown before the first ask. */
+  suggestions?: string[];
+  /** "Open chat in Oxygen" header link target (product Chat surface). */
+  threadsHref?: string;
+  open: boolean;
+  onClose: () => void;
+  className?: string;
+}
+/**
+ * The Ask Oxygen drawer. Keep it mounted and toggle `open` — the
+ * transcript survives close/reopen, matching the web-app dock.
+ */
+declare function AskDock({ agentId, workspaceName, suggestions, threadsHref, open, onClose, className }: AskDockProps): React.JSX.Element;
+//#endregion
+//#region src/shell/logoUrl.d.ts
+/** URL of the workspace logo endpoint (org-uploaded logo, falling back to
+ *  the code-first file). Consumers render an `<img>` and fall back on error.
+ *  `apiBaseUrl` is the API root (e.g. `"/api"` same-origin, or an absolute
+ *  base in dev); pass `version` (the org's `updated_at`) to bust the cache
+ *  after an upload/remove. */
+declare const workspaceLogoUrl: (apiBaseUrl: string, workspaceId: string, version?: string) => string;
+//#endregion
+//#region src/shell/marks.d.ts
+/** The Oxygen "O" glyph path, in a 0 0 44 44 viewBox, used by `OxyMark`. */
+declare const OXY_MARK_PATH = "M38.4 22C39.2837 22 40.0074 22.7178 39.9289 23.5979C39.6619 26.5942 38.6471 29.485 36.9665 32.0003C34.9886 34.9603 32.1774 37.2674 28.8883 38.6298C25.5992 39.9922 21.98 40.3487 18.4884 39.6541C14.9967 38.9596 11.7894 37.2453 9.27209 34.7279C6.75474 32.2106 5.04041 29.0033 4.34587 25.5116C3.65134 22.02 4.0078 18.4008 5.37018 15.1117C6.73255 11.8226 9.03966 9.0114 11.9997 7.03353C14.515 5.35287 17.4058 4.33807 20.4021 4.07104C21.2822 3.9926 22 4.71633 22 5.59998L22 11.2C22 12.0837 22.7163 12.8 23.6 12.8H29.2C30.0837 12.8 30.8 12.0837 30.8 11.2V5.6C30.8 4.71634 31.5163 4 32.4 4H38.4C39.2836 4 40 4.71634 40 5.6V11.6C40 12.4837 39.2836 13.2 38.4 13.2H32.8C31.9163 13.2 31.2 13.9163 31.2 14.8V20.4C31.2 21.2837 31.9163 22 32.8 22L38.4 22ZM23.6 22C22.7163 22 22 21.2837 22 20.4L22 14.8371C22 13.9534 21.2778 13.2223 20.4089 13.3827C19.2427 13.5981 18.1268 14.0489 17.1316 14.7139C15.6905 15.6768 14.5674 17.0454 13.9041 18.6466C13.2409 20.2478 13.0674 22.0097 13.4055 23.7095C13.7436 25.4094 14.5782 26.9708 15.8037 28.1963C17.0292 29.4218 18.5906 30.2564 20.2904 30.5945C21.9903 30.9326 23.7522 30.7591 25.3534 30.0959C26.9546 29.4326 28.3232 28.3095 29.2861 26.8684C29.9511 25.8732 30.4019 24.7573 30.6172 23.5911C30.7777 22.7222 30.0466 22 29.1629 22L23.6 22Z";
+/** The Oxygen "O" mark as an inline SVG that inherits `currentColor`, so it
+ *  reads correctly on any surface in light or dark mode. */
+declare function OxyMark({ className }: {
+  className?: string;
+}): import("react").JSX.Element;
+/** The Oxygen Factory mark (three-shard glyph) as an inline SVG in
+ *  `currentColor`, so it follows the shell foreground in either theme.
+ *  (The web-app's asset files are fixed-color; this inline variant frees
+ *  external bundles from carrying those assets.) Decorative — the rail
+ *  button supplies the "Oxygen Factory" aria-label. */
+declare function OxygenFactoryMark({ className }: {
+  className?: string;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/shell/OxyShell.d.ts
+interface OxyShellProps {
+  children: ReactNode;
+  /** Breadcrumb page label; defaults to this app's registered name. */
+  pageLabel?: string;
+  /** Replace the top bar's left side (the default workspace/page
+   *  breadcrumb) with the app's own brand/header content. Host-provided
+   *  slots keep rendering even when the shell bootstrap is unavailable,
+   *  so the app never loses its header by adopting the shell. */
+  topBarLeft?: ReactNode;
+  /** Extra right-side top bar content, rendered after the status cluster
+   *  (Sys · clock) and before the Ask Oxygen button. */
+  topBarExtra?: ReactNode;
+  /** Rail bottom slot content. The shell adds no built-in entries here —
+   *  a bundle that wants a Settings link supplies its own. */
+  railBottom?: ReactNode;
+  /** Drop the top bar and keep only the rail. */
+  hideTopBar?: boolean;
+  /** Bind ⌘K / Ctrl+K to toggle the Ask dock (default true). Set false
+   *  when the host app owns that shortcut; the top-bar button still works. */
+  askHotkey?: boolean;
+  /** Origin of the Oxygen product (e.g. `https://app.oxygen-hq.com`).
+   *  shell-context returns product links as relative paths, which resolve
+   *  correctly when oxy serves the bundle (production, org subdomain). In
+   *  local dev the bundle runs on its own Vite origin, so those paths would
+   *  resolve to the app's origin, not oxy's — set this to the oxy origin
+   *  and the shell rewrites Home / Chat / Settings / app links to absolute
+   *  URLs. Leave unset in production. */
+  productBaseUrl?: string;
+  className?: string;
+  /** Background of the shell chrome — the icon rail, the top bar, and the
+   *  AskDock (they share one token). Any CSS color, including `var(--…)` to
+   *  track a host token (e.g. `var(--background)` to match the app's canvas).
+   *  Overrides the theme's default; leave unset to keep it. */
+  chromeBackground?: string;
+  /** Text/icon color on the chrome, paired with `chromeBackground` for
+   *  contrast when using a background outside the current light/dark family.
+   *  Unset keeps the theme's foreground. */
+  chromeForeground?: string;
+}
+/**
+ * The workspace chrome around a customer app: icon rail + universal top bar
+ * + content column — visually identical to the main web-app shell.
+ */
+declare function OxyShell({ children, pageLabel, topBarLeft, topBarExtra, railBottom, hideTopBar, askHotkey, productBaseUrl, className, chromeBackground, chromeForeground }: OxyShellProps): import("react").JSX.Element;
+//#endregion
+//#region src/shell/trace.d.ts
+type TraceStepStatus = "running" | "done" | "failed" | "suspended";
+interface TraceItem {
+  id: string;
+  kind: "tool" | "sql" | "note" | "thinking";
+  label: string;
+  /** Muted inline preview of the tool input / query intent. */
+  preview?: string;
+  /** Right-aligned detail, e.g. "22 rows · 1.4s". */
+  detail?: string;
+  /** Body text (thinking items) — rendered as a wrapped paragraph. */
+  text?: string;
+  /** Full tool input / SQL, pretty-printed — the expandable detail body. */
+  input?: string;
+  /** Full tool output / result summary, pretty-printed. */
+  output?: string;
+  error?: boolean;
+  running?: boolean;
+}
+interface TraceStep {
+  id: string;
+  label: string;
+  summary?: string;
+  status: TraceStepStatus;
+  items: TraceItem[];
+}
+/** Fold raw SSE events into display steps. Pure — safe to re-run on every
+ *  render over the accumulated event array. */
+declare function buildTraceSteps(events: AgentRunEvent[]): TraceStep[];
+//#endregion
+//#region src/shell/ReasoningTrace.d.ts
+interface ReasoningTraceProps {
+  steps: TraceStep[];
+  /** True while the run is still streaming — keeps the trace expanded. */
+  streaming?: boolean;
+  /** Header meta from `aggregateLlmStats` (LLM call count + total time). */
+  llm?: {
+    calls: number;
+    totalMs: number;
+  };
+  className?: string;
+}
+/** Renders nothing when there are no steps (runs whose stream carries no
+ *  step events degrade to the plain answer, same as before). */
+declare function ReasoningTrace({ steps, streaming, llm, className }: ReasoningTraceProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/shell/ShellRail.d.ts
+/** One rail entry. Provide `imageUrl` (custom app mark, falls back to
+ *  `letter` on load error), `icon` (any SVG node), or `letter`.
+ *  `href` renders a real anchor (full-page nav — custom apps live outside
+ *  the SPA); `onSelect` renders a button (SPA nav, wired by the caller). */
+type RailItem = {
+  key: string;
+  label: string;
+  /** Hover-tooltip text; defaults to `label`. Use for a richer description
+   *  while keeping `label` short for the aria-label. */
+  tooltip?: string;
+  testId?: string;
+  active?: boolean;
+  icon?: ReactNode;
+  letter?: string;
+  imageUrl?: string;
+  href?: string;
+  onSelect?: () => void;
+};
+/** The icon rail. `groups` are the conceptual sections (HQ · Apps ·
+ *  Intelligence), rendered top-down with a hairline divider between them.
+ *  `footerItems` pin to the bottom of the scroll area as a distinct
+ *  "system" zone (Oxygen Factory), above the `bottom` account slot
+ *  (workspace switch · user menu — injected by the host app). */
+declare function ShellRail({ top, groups, footerItems, bottom, className }: {
+  top?: ReactNode;
+  groups: RailItem[][];
+  footerItems?: RailItem[];
+  bottom?: ReactNode;
+  className?: string;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/shell/shellContext.d.ts
+interface ShellContextApp {
+  id: string;
+  name: string;
+  slug: string;
+  /** Ready-to-navigate URL (relative on the same host, absolute across hosts). */
+  url: string;
+  icon_url?: string | null;
+  /** Agent ref the app's Ask Oxygen panel binds to (manifest `ask.agent`).
+   *  Absent → the shell hides the Ask surface for this app. */
+  default_agent?: string | null;
+  /** Composer chips for the Ask panel (manifest `ask.suggestedQuestions`). */
+  suggested_questions?: string[];
+}
+interface ShellContextData {
+  workspace: {
+    id: string;
+    name: string;
+  };
+  org: {
+    id: string;
+    slug: string;
+    name: string;
+  };
+  /** Workspace logo endpoint URL, or null when no logo is configured. */
+  logo_url: string | null;
+  /** Published custom apps in this workspace, including the current one. */
+  apps: ShellContextApp[];
+  /** Product-surface navigation targets, host-aware. `settings` opens the
+   *  Unified Settings Dialog via the SPA's `?settings=<section>` deep link
+   *  (optional: absent on servers older than the link). */
+  links: {
+    home: string;
+    threads: string;
+    settings?: string;
+  };
+  /** Viewer display identity; null on unauthenticated/local modes. */
+  user: {
+    name: string;
+    email: string;
+    picture?: string | null;
+  } | null;
+}
+interface UseShellContextResult {
+  data: ShellContextData | null;
+  loading: boolean;
+  error: Error | null;
+}
+/**
+ * Fetch the shell bootstrap payload for the current customer app. Must be
+ * called inside `<OxyAppProvider>`. Failure is non-fatal by design: the
+ * shell degrades to chrome-less rendering (older servers don't have the
+ * endpoint), so errors are surfaced on the result, never thrown.
+ */
+declare function useShellContext(): UseShellContextResult;
+//#endregion
+//#region src/shell/Tooltip.d.ts
+/**
+ * Hover tooltip for shell controls. Mirrors the web-app's Radix tooltip
+ * (zero delay, side arrow, `--zinc-200`/muted surface) but portals into the
+ * shell scope so the namespaced tokens and dark-mode class reach it.
+ */
+declare function ShellTooltip({ content, side, children }: {
+  content: React.ReactNode;
+  side?: "top" | "right" | "bottom" | "left";
+  children: React.ReactNode;
+}): React.JSX.Element;
+//#endregion
+//#region src/shell/TopBar.d.ts
+/** Frame only: left content + right cluster. Mirrors the rail's
+ *  `--sidebar-background` so the two read as one 48px-tall frame. */
+declare function TopBar({ left, right, className }: {
+  left?: ReactNode;
+  right?: ReactNode;
+  className?: string;
+}): import("react").JSX.Element;
+/**
+ * "<Workspace> / <Page>" — e.g. "Poke House / HQ". The workspace name links
+ * back to the HQ home; pass `onHomeNavigate` to intercept for SPA routing
+ * (the anchor still carries `homeHref` for middle-click/new-tab).
+ */
+declare function Breadcrumb({ workspaceLabel, pageLabel, homeHref, onHomeNavigate }: {
+  workspaceLabel: string;
+  pageLabel: string;
+  homeHref: string;
+  onHomeNavigate?: () => void;
+}): import("react").JSX.Element;
+/**
+ * Universal "Sys: Connected" indicator — a pulsing green dot when the browser
+ * is online, red when offline. Presentational connectivity signal; a real
+ * backend health ping can replace `useOnlineStatus` later without touching
+ * consumers.
+ */
+declare function SystemIndicator(): import("react").JSX.Element;
+/**
+ * Live clock in the given IANA timezone (viewer-local when omitted or
+ * invalid). Updates each half-minute (minute precision), pausing while the
+ * tab is hidden.
+ */
+declare function WorkspaceClock({ timezone }: {
+  timezone?: string;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/shell/threadHistory.d.ts
+interface ThreadSummary {
+  id: string;
+  title: string;
+  created_at: string;
+}
+interface TranscriptTurn {
+  question: string;
+  events: AgentRunEvent[];
+}
+interface ThreadTranscript {
+  title: string;
+  turns: TranscriptTurn[];
+}
+interface UseThreadHistoryResult {
+  threads: ThreadSummary[];
+  loading: boolean;
+  error: Error | null;
+  /** Re-fetch the list (call after a new chat is archived server-side). */
+  refetch: () => void;
+}
+/**
+ * List the viewer's persistent chat threads for the current project.
+ * Non-fatal on failure (older server / no session): returns an empty
+ * list so the dock falls back to session-only history.
+ */
+declare function useThreadHistory(): UseThreadHistoryResult;
+/**
+ * Fetch a thread's transcript for restore. Throws on failure so the
+ * caller can surface a toast / fall back.
+ */
+declare function fetchThreadTranscript(fetcher: AppFetcher, projectId: string, threadId: string): Promise<ThreadTranscript>;
+//#endregion
+//#region src/shell/WorkspaceTile.d.ts
+/** Rail-top workspace identity: the org/code-first logo when present, the
+ *  name initial otherwise. Pure branding — switching workspaces is the host
+ *  app's concern (the rail `bottom` slot). */
+declare function WorkspaceTile({ name, logoUrl }: {
+  name: string;
+  logoUrl?: string;
+}): import("react").JSX.Element;
+//#endregion
+export { AnswerChart, type AnswerChartProps, AskDock, type AskDockProps, Breadcrumb, type ChartBlock, type ChartBlockConfig, OXY_MARK_PATH, OxyMark, OxyShell, type OxyShellProps, OxygenFactoryMark, type RailItem, ReasoningTrace, type ReasoningTraceProps, type ShellContextApp, type ShellContextData, ShellRail, ShellTooltip, SystemIndicator, type ThreadSummary, type ThreadTranscript, TopBar, type TraceItem, type TraceStep, type TraceStepStatus, type TranscriptTurn, type UseShellContextResult, type UseThreadHistoryResult, WorkspaceClock, WorkspaceTile, buildTraceSteps, fetchThreadTranscript, useShellContext, useThreadHistory, workspaceLogoUrl };
+//# sourceMappingURL=shell.d.mts.map

package/dist/shell.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.mts","names":[],"sources":["../src/shell/AnswerChart.tsx","../src/shell/AskDock.tsx","../src/shell/logoUrl.ts","../src/shell/marks.tsx","../src/shell/OxyShell.tsx","../src/shell/trace.ts","../src/shell/ReasoningTrace.tsx","../src/shell/ShellRail.tsx","../src/shell/shellContext.ts","../src/shell/Tooltip.tsx","../src/shell/TopBar.tsx","../src/shell/threadHistory.ts","../src/shell/WorkspaceTile.tsx"],"mappings":";;;;;UAYiB;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf,QAAQ;EACR;EACA;;UA8ce;EACf,OAAO;EACP;;;;;iBAMc,cAAc,OAAO,aAAa,mBAAgB,MAAA,IAAA;;;UCzUjD;;EAEf;;EAEA;;EAEA;;EAEA;EACA;EACA;EACA;;;;;;iBAuEc,UACd,SACA,eACA,aACA,aACA,MACA,SACA,aACC,eAAY,MAAA,IAAA;;;;;;;;cC7PF,mBAAgB,oBAAsB,qBAAqB;;;;cCA3D;;;iBAKG,UAAU;EAAe;oBAAoB,IAAA;;;;;;iBAyB7C,oBAAoB;EAAe;oBAAoB,IAAA;;;UC+BtD;EACf,UAAU;;EAEV;;;;;EAKA,aAAa;;;EAGb,cAAc;;;EAGd,aAAa;;EAEb;;;EAGA;;;;;;;;EAQA;EACA;;;;;EAKA;;;;EAIA;;;;;;iBAsDc,WACd,UACA,WACA,YACA,aACA,YACA,YACA,WACA,gBACA,WACA,kBACA,oBACC,gCAAa,IAAA;;;KC9JJ;UAEK;EACf;EACA;EACA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA,QAAQ;EACR,OAAO;;;;iBA8IO,gBAAgB,QAAQ,kBAAkB;;;UCvDzC;EACf,OAAO;;EAEP;;EAEA;IAAQ;IAAe;;EACvB;;;;iBAKc,iBAAiB,OAAO,WAAmB,KAAK,aAAa,sCAAmB,IAAA;;;;;;;KCxHpF;EACV;EACA;;;EAGA;EACA;EACA;EACA,OAAO;EACP;EACA;EACA;EACA;;;;;;;iBAuDc,YACd,KACA,QACA,aACA,QACA;EAEA,MAAM;EACN,QAAQ;EACR,cAAc;EACd,SAAS;EACT;oBACD,IAAA;;;UC9EgB;EACf;EACA;EACA;;EAEA;EACA;;;EAGA;;EAEA;;UAGe;EACf;IAAa;IAAY;;EACzB;IAAO;IAAY;IAAc;;;EAEjC;;EAEA,MAAM;;;;EAIN;IAAS;IAAc;IAAiB;;;EAExC;IAAQ;IAAc;IAAe;;;UAGtB;EACf,MAAM;EACN;EACA,OAAO;;;;;;;;iBASO,mBAAmB;;;;;;;;iBC/CnB,eACd,SACA,MACA;EAEA,SAAS,MAAM;EACf;EACA,UAAU,MAAM;IACjB,MAAA,IAAA;;;;;iBCNe,SACd,MACA,OACA;EAEA,OAAO;EACP,QAAQ;EACR;oBACD,IAAA;;;;;;iBAqBe,aACd,gBACA,WACA,UACA;EAEA;EACA;EACA;EACA;oBACD,IAAA;;;;;;;iBAmDe,mCAAe,IAAA;;;;;;iBA+Bf,iBAAiB;EAAc;oBAAmB,IAAA;;;UCrHjD;EACf;EACA;EACA;;UAGe;EACf;EACA,QAAQ;;UAGO;EACf;EACA,OAAO;;UAGQ;EACf,SAAS;EACT;EACA,OAAO;;EAEP;;;;;;;iBAQc,oBAAoB;;;;;iBAyCd,sBACpB,SAAS,YACT,mBACA,mBACC,QAAQ;;;;;;iBCpFK,gBAAgB,MAAM;EAAa;EAAc;oBAAkB,IAAA"}