@oxy-hq/sdk 2.9.1 → 2.11.0

package/dist/{react-DBG6Pfp_.d.cts → react-CLONxcnA.d.mts}

@@ -64,6 +64,44 @@ interface OxyAppFunctionManifest {
   email?: {
     send?: boolean;
   };
+  /**
+   * Capability for `ctx.org.people()` — the org's people directory, READ-ONLY
+   * (fail-closed: omit → the call is rejected before any query).
+   *
+   * Declare it for a function that has to name a person: an assignee, a roster
+   * entry, who submitted something. It answers with a display name and a role.
+   *
+   * Three things it deliberately is not, so nobody plans around them:
+   * it returns **no email and no phone** — naming a colleague is a different
+   * need from contacting them off-platform; it returns **no location**, which
+   * the platform does not hold for a member; and it does **not include
+   * frontline workers**, who hold no org-membership row by design.
+   *
+   * One flag, not `read`/`write`: there is no write. Editing the directory
+   * would put tenant membership behind an app's manifest.
+   */
+  org?: {
+    read?: boolean;
+  };
+  /**
+   * Capability for `ctx.oltp` — read/write the app's OWN per-org OLTP schema on
+   * the managed Postgres tenant (fail-closed: omit → every `ctx.oltp` call
+   * rejected). A pure GATE: the target schema is derived from the app's own slug
+   * host-side (`oltp-bookings` → `app_oltp_bookings`), never named here, so a
+   * manifest cannot point `ctx.oltp` at another app's schema. The resolved role
+   * has DML rights on that one schema and nothing else — reaching neither another
+   * app's data nor the analyst-visible `raw_*` schemas. The store must be
+   * provisioned first (ask whoever operates the org).
+   *
+   * NOTE: this shape is `{ enabled }`, not the earlier `{ writer }` — an app
+   * had no business naming its own writer (that was the cross-app hole). A
+   * manifest still carrying `"oltp": { "writer": "…" }` deserializes to
+   * `enabled: undefined` → **disabled**, and `ctx.oltp` then reports the
+   * capability as missing. Switch it to `{ "enabled": true }`.
+   */
+  oltp?: {
+    enabled?: 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
@@ -120,6 +158,25 @@ interface OxyAppManifest {
    * static bundle (today's default). See the functions design doc.
    */
   functions?: Record<string, OxyAppFunctionManifest>;
+  /**
+   * Schema migrations that ship WITH this bundle and run on promote.
+   *
+   * `dir` is a directory inside the built bundle holding numbered `.sql` files.
+   * The platform runs them in lexical order, **once each, ever**, inside a
+   * transaction, as the app's own writer role, and records each one.
+   *
+   * What changes for the author: you no longer write defensive
+   * `IF NOT EXISTS` / idempotent upserts, because re-running is a no-op by
+   * construction rather than by your care. And you **may not edit, rename or
+   * copy a migration that has already run** — all three fail the promote by
+   * name, and the fix is always a new file.
+   *
+   * The `.sql` files are ordinary bundle files, fetchable over the app's own
+   * host: put no secrets in them.
+   */
+  migrations?: {
+    dir: string;
+  };
   /**
    * Optional Ask Oxygen binding (agent ref + composer chips). The
    * platform's registered copy is authoritative (surfaced by
@@ -137,6 +194,46 @@ interface OxyAppManifest {
    * shares.
    */
   storage?: OxyAppStorageManifest;
+  /**
+   * Browser-runtime performance opt-outs. Both features below are **on by
+   * default** — an app that says nothing gets them — so this block exists only
+   * to turn one off.
+   *
+   * Read by the platform at **publish time** (like {@link OxyAppStorageManifest})
+   * rather than by this loader, so the field is documented here but not
+   * round-tripped through the dev-time manifest fetch.
+   */
+  performance?: OxyAppPerformanceManifest;
+  /**
+   * Opt out of the platform's automatic, zero-config usage instrumentation:
+   * SPA pageviews, Core Web Vitals, engagement time, and uncaught-error counts,
+   * posted to `<base>/__oxy/beacon` by the runtime Oxy injects into every served
+   * page. `false` silences the **client** runtime only — the server still
+   * records one view row per HTML navigation (that floor is not opt-out-able),
+   * so the Activity tab never goes dark, it just loses the in-page detail.
+   *
+   * Distinct from `useTrackEvent` (your own named events): those are additive and
+   * always on. This governs only the events the platform sends on your behalf.
+   *
+   * Honored at publish time (see {@link performance} for why it is not
+   * round-tripped here). Default: `true`.
+   */
+  analytics?: boolean;
+}
+/** Browser-runtime performance opt-outs — the `performance` block in `oxy-app.json`. */
+interface OxyAppPerformanceManifest {
+  /**
+   * Opt out of the platform service worker Oxy registers at `<base>/__oxy/sw.js`.
+   * It precaches your build's entry assets and serves content-hashed files
+   * cache-first, so a repeat load of a published app is near-instant.
+   *
+   * Set `false` only if your app ships its own service worker (two workers
+   * cannot both control the same scope) or genuinely must never be cached.
+   * There is nothing to configure to opt *in* — a normal build is precached
+   * automatically, and a bundle that inlines everything into one HTML file
+   * simply has nothing to precache, which is fine. Default: `true`.
+   */
+  serviceWorker?: boolean;
 }
 /** How long assets under a given prefix are kept. */
 interface OxyAppRetentionRule {
@@ -270,6 +367,27 @@ interface FunctionLog {
   level: string;
   message: string;
 }
+/** A successful function result plus the logs captured during the run. */
+interface FunctionResult<Data> {
+  value: Data;
+  logs: FunctionLog[];
+}
+/**
+ * An error carries the logs captured before the throw, so the app can show them.
+ *
+ * `status` is the HTTP status the FUNCTION returned, present when the function
+ * ran and answered a non-2xx. It is absent when the run itself failed (an
+ * `event: error` frame — a crash, a timeout, a cancellation), because there was
+ * no response to have a status.
+ *
+ * `body` is the parsed payload the function returned with that status, so a
+ * caller can read `{ error: "…" }` without re-parsing the message.
+ */
+type FunctionError = Error & {
+  logs?: FunctionLog[];
+  status?: number;
+  body?: unknown;
+};
 //#endregion
 //#region src/custom-app/react.d.ts
 /**
@@ -340,6 +458,12 @@ declare function useResolvedManifest(): ResolvedCustomAppManifest;
  */
 declare function useOxyApp(): {
   projectId: string | undefined;
+  /**
+   * The `apps.id` this bundle was served as — from `window.__OXY_APP__`, so
+   * it is the platform's word and not the manifest's. Undefined under `pnpm
+   * dev` against a manifest with no injected identity.
+   */
+  appId: string | undefined;
   appSlug: string | undefined;
   orgSlug: string | undefined;
   fetcher: AppFetcher;
@@ -469,7 +593,7 @@ interface UseSemanticQueryResult<Row = Record<string, unknown>> {
   refetch: () => void;
 }
 /**
- * Run a semantic-layer query against the project's `.view.yml` /
+ * Run a semantic-model 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.
@@ -704,5 +828,5 @@ interface OxyChatProps {
  */
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
-export { UseSemanticQueryOpts as A, CustomAppErrorReport as B, UseProcedureRunInput as C, UseQueryOpts as D, UseQueryInput as E, useProcedureRun as F, OxyAppFunctionManifest as G, apiErrorFromResponse as H, useQuery as I, _resetCustomAppManifestCacheForTest 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, interpretCustomAppError as U, OxyApiError as V, LoadManifestOptions as W, loadCustomAppManifest 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, ResolvedCustomAppManifest 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-DBG6Pfp_.d.cts.map
+export { loadCustomAppManifest as $, UseSemanticQueryOpts as A, FunctionError as B, UseProcedureRunInput as C, UseQueryOpts as D, UseQueryInput as E, useProcedureRun as F, apiErrorFromResponse as G, FunctionResult as H, useQuery as I, OxyAppFunctionManifest as J, interpretCustomAppError as K, useResolvedManifest as L, useAgentRun as M, useFunction as N, UseQueryResult as O, useOxyApp as P, _resetCustomAppManifestCacheForTest as Q, useSemanticQuery as R, UseFunctionResult as S, UseProcedureRunResult as T, CustomAppErrorReport as U, FunctionLog as V, OxyApiError as W, OxyAppPerformanceManifest as X, OxyAppManifest as Y, ResolvedCustomAppManifest as Z, 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, LoadManifestOptions 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-CLONxcnA.d.mts.map

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

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

package/dist/{react-sACIu6Ea.mjs → react-DqnINwTi.mjs}

@@ -272,6 +272,7 @@ function validateManifest(raw, url) {
 	if (raw.schemaVersion !== 2) throw new Error(`oxy-app.json: schemaVersion must be 2 (got ${JSON.stringify(raw.schemaVersion)}). v1 manifests are no longer supported — upgrade to the identity-only shape.`);
 	if (raw.products !== void 0 || raw.writers !== void 0) throw new Error(`oxy-app.json is schemaVersion 2 (identity-only); \`products\` and \`writers\` are no longer supported`);
 	if (typeof raw.slug !== "string" || !raw.slug.trim()) throw new Error("oxy-app.json: `slug` is required and must be a non-empty string");
+	if (!isValidSlug(raw.slug)) throw new Error(`oxy-app.json: \`slug\` ${JSON.stringify(raw.slug)} is invalid — use 1–63 lowercase letters, digits and single hyphens (no leading/trailing/double hyphen, no underscore)`);
 	return {
 		schemaVersion: 2,
 		name: typeof raw.name === "string" ? raw.name : void 0,
@@ -285,12 +286,21 @@ function validateManifest(raw, url) {
 		} : void 0
 	};
 }
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function isValidSlug(s) {
+	return s.length <= 63 && SLUG_RE.test(s);
+}
 const FUNCTION_NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
 /**
-* Validate the optional `functions` map. Each key is a function name;
-* each value declares how the function is invoked. Mirrors the
-* server-side validation in `custom_apps_publish.rs` so a bad
-* manifest fails at build, not at publish.
+* Validate the optional `functions` map. Each key is a function name; each value
+* declares how the function is invoked. Mirrors the server-side function-name
+* rule enforced at publish in `custom_apps_publish.rs` — `is_valid_function_name`,
+* checked in `record_functions` before any row is written.
+*
+* This runs at manifest LOAD (app boot / `pnpm dev`), not at `oxy build` — the
+* build-time gate is the vite plugin's `validateManifest`, which now checks
+* function names too. `oxy publish` also validates them locally before esbuild,
+* so a bad name fails before the upload regardless.
 */
 function validateFunctions(raw) {
 	if (!isRecord(raw)) throw new Error("oxy-app.json: `functions` must be an object keyed by function name");
@@ -419,11 +429,24 @@ async function readFunctionSseStream(resp) {
 			});
 		} catch {}
 		else if (event === "data") dataPayload = data;
-		else if (event === "done") return {
-			done: true,
-			value: dataPayload ? JSON.parse(dataPayload) : null
-		};
-		else if (event === "error") {
+		else if (event === "done") {
+			const parsed = dataPayload ? JSON.parse(dataPayload) : null;
+			const meta = data ? JSON.parse(data) : {};
+			const status = typeof meta.status === "number" ? meta.status : 200;
+			if (status < 200 || status >= 300) {
+				const payload = parsed;
+				const err = new Error(String(payload?.message ?? payload?.error ?? `function returned ${status}`));
+				err.name = "FunctionStatusError";
+				err.status = status;
+				err.body = parsed;
+				err.logs = logs;
+				throw err;
+			}
+			return {
+				done: true,
+				value: parsed
+			};
+		} else if (event === "error") {
 			const payload = data ? JSON.parse(data) : {};
 			const err = new Error(payload.message || payload.error || "function invocation failed");
 			err.name = payload.error || "FunctionError";
@@ -749,6 +772,7 @@ function useOxyApp() {
 	if (!ctx) throw new Error("useOxyApp must be called inside <OxyAppProvider>");
 	return {
 		projectId: ctx.resolved?.projectId,
+		appId: ctx.resolved?.appId,
 		appSlug: ctx.resolved?.appSlug,
 		orgSlug: ctx.resolved?.orgSlug,
 		fetcher: ctx.fetcher
@@ -913,7 +937,7 @@ function useFunction(name) {
 	};
 }
 /**
-* Run a semantic-layer query against the project's `.view.yml` /
+* Run a semantic-model 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.
@@ -1535,7 +1559,7 @@ function sleep(ms, signal) {
 * within-limit events are unaffected.
 */
 function useTrackEvent() {
-	const { projectId, fetcher } = useOxyApp();
+	const { projectId, appId, fetcher } = useOxyApp();
 	const queueRef = React.useRef([]);
 	const flushTimerRef = React.useRef(null);
 	const flush = React.useCallback(() => {
@@ -1546,7 +1570,10 @@ function useTrackEvent() {
 		queueRef.current = [];
 		for (const evt of batch) {
 			const url = `/api/customer-apps/${projectId}/events`;
-			const body = JSON.stringify(evt);
+			const body = JSON.stringify(appId ? {
+				...evt,
+				app_id: appId
+			} : evt);
 			try {
 				if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" && document.visibilityState === "hidden") navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
 				else fetcher(url, {
@@ -1560,7 +1587,11 @@ function useTrackEvent() {
 				console.warn("[oxy] useTrackEvent enqueue failed:", e);
 			}
 		}
-	}, [projectId, fetcher]);
+	}, [
+		projectId,
+		fetcher,
+		appId
+	]);
 	React.useEffect(() => {
 		if (typeof window === "undefined") return;
 		const onHide = () => flush();
@@ -2261,4 +2292,4 @@ const styles = {
 
 //#endregion
 export { interpretCustomAppError as _, useFunction as a, useQuery as c, useTrackEvent as d, _resetCustomAppManifestCacheForTest as f, apiErrorFromResponse as g, OxyApiError as h, useAgentRun as i, useResolvedManifest as l, readInjectedAppConfig as m, OxyAppProvider as n, useOxyApp as o, loadCustomAppManifest as p, OxyChat as r, useProcedureRun as s, OxyAnswer as t, useSemanticQuery as u, getOxyAppLogger as v, setOxyAppLogger as y };
-//# sourceMappingURL=react-sACIu6Ea.mjs.map
+//# sourceMappingURL=react-DqnINwTi.mjs.map