@oxy-hq/sdk 2.8.0 → 2.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 React SDK for building **custom-app bundles** on the [Oxy](https://oxygen-hq.com)
 platform. A bundle is a normal Vite + React app that reads from its linked oxy
-project — raw SQL, the semantic layer, agents, and procedures — through a
+project — raw SQL, the semantic model, agents, and procedures — through a
 small set of hooks, plus a couple of drop-in components.
 
 > **v2 is a complete rewrite.** The v1 stack (`OxyClient` / `OxySDK`, the
@@ -80,7 +80,7 @@ couldn't already read.
 | --- | --- |
 | `OxyAppProvider` | Resolves identity, provides it via context. `fallback` renders while loading; `errorFallback` gets a structured error report. |
 | `useQuery({ sql })` | Inline SQL → rows. `SELECT`/`WITH` only, 10k-row cap. |
-| `useSemanticQuery({ topic, dimensions, measures, … })` | Semantic-layer query compiled by airlayer. |
+| `useSemanticQuery({ topic, dimensions, measures, … })` | Semantic-model query compiled by airlayer. |
 | `useAgentRun({ agentId })` | `.ask(question)` starts an analytics agent run; streams events over SSE; `.cancel()`. |
 | `useProcedureRun({ procedureId })` | Start a long-running procedure, poll, cancel (beta). |
 | `useFunction(name)` | `.invoke(body?)` runs a server-side **Oxy Function** (`functions/<name>.ts`) on oxy's isolate runtime; returns its JSON `Response`. For work the browser shouldn't do — warehouse writes, ELT, external APIs. |
@@ -188,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"}

package/dist/index.cjs

@@ -1,10 +1,20 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_react = require('./react-BFFCK4VM.cjs');
+const require_react = require('./react-Cas_DVKe.cjs');
 let react = require("react");
 react = require_react.__toESM(react, 1);
 
 //#region src/anomalies.ts
+/** Which buckets a write may touch when the caller didn't say. Live statuses
+*  for ack/dismiss; all three for a reopen, which exists to reach dismissed
+*  ones. */
+function defaultScope(status) {
+	return status === "new" ? [
+		"new",
+		"acknowledged",
+		"dismissed"
+	] : ["new", "acknowledged"];
+}
 /**
 * Client for `/semantic/anomalies*`. Construct via `OxyClient.anomalies`
 * rather than instantiating directly — the getter wires the request helper
@@ -33,18 +43,25 @@ var AnomaliesClient = class {
 		return qs ? `?${qs}` : "";
 	}
 	/**
-	* List anomalies in the inbox, newest first.
+	* List anomalies in the inbox, ranked worst-first by event severity (active
+	* events before dismissed). Pass `order: "recent"` for latest-first.
 	*
 	* @example
 	* ```typescript
 	* // Open / unresolved anomalies only
 	* const { anomalies } = await client.anomalies.list({ status: "new" });
+	*
+	* // Second page of 25 events
+	* const page2 = await client.anomalies.list({ limit: 25, offset: 25 });
+	* console.log(`${(page2.offset ?? 25) + 1}+ of ${page2.total ?? "?"}`);
 	* ```
 	*/
 	async list(options = {}) {
 		const extra = {};
 		if (options.status) extra.status = options.status;
-		if (options.limit) extra.limit = String(options.limit);
+		if (options.limit !== void 0) extra.limit = String(options.limit);
+		if (options.offset !== void 0) extra.offset = String(options.offset);
+		if (options.order) extra.order = options.order;
 		return this.request(this.path(this.buildQuery(extra)));
 	}
 	/**
@@ -84,6 +101,51 @@ var AnomaliesClient = class {
 		});
 	}
 	/**
+	* Update many anomalies in one request — the batch form of
+	* {@link updateStatus}. Identifiers outside the workspace are skipped rather
+	* than erroring, so `updated` (rows written) can be lower than what you sent.
+	* At most 2000 identifiers across both lists.
+	*
+	* **Prefer `eventIds`.** Inbox actions are per *event*, and a list response
+	* caps how many buckets it returns per event — so acking the bucket ids you
+	* received can leave the tail of a long chain behind, `new`, under a clean
+	* success. Naming the event lets the server write all of it. `ids` is for
+	* rows with no `event_id` (detected before events existed), which can only
+	* be named individually.
+	*
+	* `onlyStatuses` says which of an event's buckets may move. An event can span
+	* statuses, so an unbounded write resurrects buckets that were dismissed on
+	* purpose — which is why omitting it takes a scope rather than no bound at
+	* all: the live statuses (`["new", "acknowledged"]`) for an ack or dismiss,
+	* and all three for `status: "new"`, since reopening is how a dismissed
+	* anomaly comes back. The server applies that same default, so the safe
+	* behaviour does not depend on going through this client. Pass `[]` to opt
+	* out of the bound entirely.
+	*
+	* @example
+	* ```typescript
+	* const { anomalies } = await client.anomalies.list({ status: "new", limit: 50, offset: 0 });
+	* // Both lists: events by id, and pre-event rows (no `event_id`) by their own.
+	* const eventIds = [...new Set(anomalies.flatMap((a) => (a.event_id ? [a.event_id] : [])))];
+	* const ids = anomalies.filter((a) => !a.event_id).map((a) => a.id);
+	* const { updated } = await client.anomalies.updateStatusBulk(
+	*   { ids, eventIds, onlyStatuses: ["new", "acknowledged"] },
+	*   "acknowledged"
+	* );
+	* ```
+	*/
+	async updateStatusBulk(target, status) {
+		return this.request(this.path(`/status${this.buildQuery()}`), {
+			method: "POST",
+			body: JSON.stringify({
+				ids: target.ids ?? [],
+				event_ids: target.eventIds ?? [],
+				only_statuses: target.onlyStatuses ?? defaultScope(status),
+				status
+			})
+		});
+	}
+	/**
 	* Run the metric-tree `explain` for an anomaly and cache the result on
 	* the row. Subsequent calls return the cached `ExplainResult` instantly;
 	* pass `{ refresh: true }` to bust the cache and recompute.
@@ -436,7 +498,7 @@ function worldModelPath(projectId) {
 * project's `.world-model.yml` display config server-side.
 *
 * @remarks
-* This returns the raw semantic-layer entity graph. For the higher-level
+* This returns the raw semantic-model entity graph. For the higher-level
 * node-paradigm interface (`world.metric(id)` speaking `expand` / `explain` /
 * `size`), use {@link useWorldModel} from `./world-node` instead.
 */
@@ -745,7 +807,7 @@ function createWorldModel(projectId, fetcher) {
 * ```
 *
 * @remarks
-* This is the node-paradigm hook. For the raw semantic-layer entity/measure
+* This is the node-paradigm hook. For the raw semantic-model entity/measure
 * graph, use {@link useWorldModelGraph} instead.
 */
 function useWorldModel() {