@oxy-hq/sdk 2.6.0 → 2.9.1

package/README.md

@@ -88,11 +88,61 @@ couldn't already read.
 | `<OxyAnswer … />` | Renders markdown + SQL artifacts + thread link. URL schemes are allowlisted (rejects `javascript:` etc.). |
 | `OxyApiError` | Structured `{ message, code? }` server-error envelope. |
 
-### Metric Tree
+### World Model & analysis hooks
 
-Additional exports for programmatic metric-tree analyses (`AnomaliesClient`,
-`MetricTreeClient` and all related types) are available from the package root
-— see [metricTree.ts](src/metricTree.ts) and [anomalies.ts](src/anomalies.ts).
+The same airlayer analyses the IDE's **World Model** and **Metric Tree** run,
+exposed as hooks so a bundle can do RCA, opportunity sizing, and driver
+exploration itself. Each fetches when enabled and its input is present; pass
+`null` for a request/id to keep a hook idle until the user makes a selection.
+
+| Export | What it does |
+| --- | --- |
+| `useWorldModel()` | The entity/measure graph — entities, their measures, and how measures promote across the hierarchy (edges). |
+| `useWorldModelInstances(entityId, { search?, limit? })` | Searchable listing of an entity's instances (primary key + display label). |
+| `useMetricTree({ root? })` | The metric tree (measures + component/driver edges), or the subtree at `root`. |
+| `useSensitivity(measureId)` | Ranked **drivers** of a measure — "what moves this?" |
+| `usePredict(changes)` | **What-if**: propagate hypothetical `(measure, delta)` changes upward (pure tree walk, no warehouse). |
+| `useExplain(request)` | **RCA**: period-over-period root-cause decomposition. |
+| `useOpportunity(request)` | Segment **opportunity sizing** — addressable upside vs a benchmark peer. |
+| `useDistribution(request)` | Single-period distribution against an auto-derived prior baseline. |
+| `useTimeDimensions()` | Valid time dimensions per view — the period axis for the ops above. |
+| `useMeasureBreakdown(entityId, key, measure)` | Per-instance **driver tree** (SSE) — node values fill in as they resolve. |
+
+```tsx
+import { OxyAppProvider, useExplain, useOpportunity } from "@oxy-hq/sdk";
+
+function RootCause() {
+  // Pass `null` instead of the request object to defer until the user picks a period.
+  const { data, loading, error } = useExplain({
+    target: "financials.operating_profit",
+    time_dimension: "financials.month",
+    current_period: ["2025-09-01", "2025-09-30"],
+    previous_period: ["2025-08-01", "2025-08-31"]
+  });
+  if (loading) return <p>Explaining…</p>;
+  if (error) return <p>{error.message}</p>;
+  return <p>Δ {data?.target_delta} — {((data?.coverage ?? 0) * 100).toFixed(0)}% explained</p>;
+}
+
+function Upside() {
+  const { data } = useOpportunity({
+    target: "orders.net_revenue",
+    time_dimension: "orders.order_date",
+    period: ["2025-04-01", "2025-06-30"]
+  });
+  return <>{data?.dimensions.map((d) => <p key={d.dimension}>{d.dimension}: +{d.total_upside}</p>)}</>;
+}
+```
+
+A fuller worked example (graph + opportunity + RCA + streaming driver tree) is
+in [examples/world-model-analysis.tsx](examples/world-model-analysis.tsx).
+
+### Metric Tree (client-class)
+
+For non-React / API-key callers, the programmatic `MetricTreeClient` and
+`AnomaliesClient` (and all related types) are available from the package root
+— see [metricTree.ts](src/metricTree.ts), [anomalies.ts](src/anomalies.ts), and
+[examples/metric-tree.ts](examples/metric-tree.ts).
 
 Hooks fail loudly if called outside `<OxyAppProvider>`. The default fetcher
 sends `credentials: "include"` so same-origin (served-by-oxy) calls carry the
@@ -138,12 +188,67 @@ global styles leak into your app. It follows your design tokens when present
 (`--sidebar-background`, `--foreground`, …) and falls back to the Oxygen
 defaults. Dark mode: put a `.dark` class on any ancestor.
 
+## Who is using the app
+
+Two identity surfaces, and the difference between them is the difference between
+a decision and a greeting.
+
+**`ctx.user`, inside an Oxy Function — authoritative.** Assembled server-side per
+invocation from the authenticated session, so nothing on it is client-supplied.
+This is where a check that matters goes:
+
+```ts
+import type { OxyFunctionContext, OxyFunctionRequest } from "@oxy-hq/sdk";
+
+export default async function exportAll(req: OxyFunctionRequest, ctx: OxyFunctionContext) {
+  if (ctx.user.appRole !== "admin") {
+    return Response.json({ error: "forbidden" }, { status: 403 });
+  }
+  return Response.json({ rows: await dump(ctx) });
+}
+```
+
+| Field | Notes |
+| --- | --- |
+| `id`, `email`, `orgId` | Always present. `orgId` is the tenant boundary for anything you query. |
+| `name`, `picture` | Display identity. Absent on schedule/Airway runs. |
+| `appRole` | `"admin"` \| `"member"` \| absent. **The one to gate on** — an app grant (direct or via a team), with org-officer / Oxy-staff break-glass. Fails closed. |
+| `orgRole` | `"owner"` \| `"admin"` \| `"member"` \| absent. Informational: explain ("ask your org admin"), label, route. Not a gate — org standing and app standing are different things. |
+| `teams` | Org teams they belong to, name-sorted, scoped to this org. Descriptive — a team only grants anything through an app team grant, which `appRole` already reflects. |
+| `kind` | `"user"` \| `"system"`. |
+
+`teams` and `kind` are typed optional because a server older than 2026-08-21
+doesn't send them — use `ctx.user.teams?.some(...)`. For `kind` there is no safe
+inference on such a server (`=== "system"` misses a cron, `!== "user"` misfires
+on a person), so if you support one, mark the schedule's configured `input`
+instead of guessing.
+
+**Background runs have no caller to attribute them to.** A schedule tick, an
+Airway step, and an operator's manual *Run now* all run under the org owner's
+`id` with `kind: "system"`, every caller field absent, and a synthetic
+`schedule+<fn>@system.oxy` email — but `appRole` still reads `"admin"`, since
+they carry owner authority. Note the manual case: a person did click, and there
+is still nobody to reach, because the triggering operator isn't carried through
+the job queue. A function wired to both a route and a background trigger must
+branch on `kind`, not on the email:
+
+```ts
+if (ctx.user.kind === "system") return runRollup(ctx);   // no one to email
+await ctx.email.send({ to: ctx.user.email, subject: `Hi ${ctx.user.name}`, html });
+```
+
+**`useShellContext()`, in the bundle — display only.** `data.user` is
+`{ name, email, picture } | null`, and it deliberately carries no role at all.
+Use it for an avatar or a greeting. Hiding a tab with it is fine; the endpoint
+behind that tab is what actually has to say no.
+
 ## Docs
 
 - Hands-on dev + deploy guide: `docs/local-development.md` in the
   [`oxy-hq/customer-apps`](https://github.com/oxy-hq/customer-apps) repo.
 - SDK flow reference: `docs/sdk-flow.md` in that repo.
-- Platform internals: `internal-docs/customer-apps.md` in oxygen-internal.
+- Platform internals: `internal-docs/customer-apps.md` and
+  `internal-docs/custom-apps-user-identity.md` in oxygen-internal.
 
 
 ## License

package/dist/email.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"email.cjs","names":[],"sources":["../src/email.ts"],"sourcesContent":["// `@oxy-hq/sdk/email` — render an email template to an HTML string for use in\n// an Oxy Function's `ctx.email.send`.\n//\n// You write email templates as plain JSX components (point JSX at preact with\n// `jsxImportSource: \"preact\"` in the template's tsconfig — see the examples),\n// then:\n//\n// ```ts\n// import { render } from \"@oxy-hq/sdk/email\";\n// import { Welcome } from \"../emails/Welcome\";\n// await ctx.email.send({ to, subject, html: render(Welcome, { name }) });\n// ```\n//\n// Rendering uses preact-render-to-string — pure JS, no react-dom/server, no node\n// builtins, no Web Streams — so it bundles under esbuild `--platform=neutral`\n// and runs inside the Oxy Functions isolate (React Email / react-dom cannot).\n// Kept in a separate subpath entry so it never bloats the main SDK bundle.\n\nimport { type ComponentType, h } from \"preact\";\nimport { render as prerender } from \"preact-render-to-string\";\n\n/** Render an email template component to an HTML string. */\nexport function render<P extends Record<string, unknown>>(\n  Component: ComponentType<P>,\n  props: P\n): string {\n  return prerender(h(Component, props));\n}\n"],"mappings":";;;;;;;AAsBA,SAAgB,OACd,WACA,OACQ;CACR,yDAAmB,WAAW,KAAK,CAAC;AACtC"}
+{"version":3,"file":"email.cjs","names":["prerender","h"],"sources":["../src/email.ts"],"sourcesContent":["// `@oxy-hq/sdk/email` — render an email template to an HTML string for use in\n// an Oxy Function's `ctx.email.send`.\n//\n// You write email templates as plain JSX components (point JSX at preact with\n// `jsxImportSource: \"preact\"` in the template's tsconfig — see the examples),\n// then:\n//\n// ```ts\n// import { render } from \"@oxy-hq/sdk/email\";\n// import { Welcome } from \"../emails/Welcome\";\n// await ctx.email.send({ to, subject, html: render(Welcome, { name }) });\n// ```\n//\n// Rendering uses preact-render-to-string — pure JS, no react-dom/server, no node\n// builtins, no Web Streams — so it bundles under esbuild `--platform=neutral`\n// and runs inside the Oxy Functions isolate (React Email / react-dom cannot).\n// Kept in a separate subpath entry so it never bloats the main SDK bundle.\n\nimport { type ComponentType, h } from \"preact\";\nimport { render as prerender } from \"preact-render-to-string\";\n\n/** Render an email template component to an HTML string. */\nexport function render<P extends Record<string, unknown>>(\n  Component: ComponentType<P>,\n  props: P\n): string {\n  return prerender(h(Component, props));\n}\n"],"mappings":";;;;;;;AAsBA,SAAgB,OACd,WACA,OACQ;CACR,WAAOA,oCAAUC,UAAE,WAAW,KAAK,CAAC;AACtC"}