@oxy-hq/sdk 2.10.0 → 2.12.0

package/dist/ops.d.cts

@@ -0,0 +1,61 @@
+
+import { _ as OxyReach } from "./function-context-D8eyZuw_.cjs";
+//#region src/ops/index.d.ts
+/** What `ctx.user.reach` carries — one shape, declared once on the context type. */
+type Reach = OxyReach;
+/** The slice of `ctx` this module reads — a test hands in exactly this. */
+interface ReachCtx {
+  user: {
+    /**
+     * Present on every invocation since SDK 2.12 / the operating graph. Typed
+     * optional here so a function can be written before its server is
+     * upgraded: an absent reach is the fail-closed answer, never the office.
+     */
+    reach?: Reach | null;
+    appRole?: string;
+    kind?: string;
+  };
+}
+/**
+ * The caller's reach. Synchronous — the platform decided it before the
+ * function ran — but `await reachOf(ctx)` still works, so code written against
+ * the app-side version keeps compiling.
+ *
+ * Absent reach (an older server) lands on nowhere. Not "system reaches
+ * everywhere, everyone else nowhere": a system invocation on an older server
+ * carries no reach either, and the one thing this module must never do is
+ * invent a wider answer than the platform gave.
+ */
+declare function reachOf(ctx: ReachCtx): Reach;
+declare function reaches(reach: Reach, locationId: string): boolean;
+/**
+ * For a writer naming a location: the 403 to return, or null to proceed.
+ *
+ * The message names the location and not the roster, and the code is stable:
+ * the client tells "you are not rostered here" from "no such location" (a 404
+ * the writers answer BEFORE this) and from "admin only" (a 403 with another
+ * code) without parsing English.
+ */
+declare function requireReach(ctx: ReachCtx, locationId: string): Response | null;
+/**
+ * For a reader: a SQL expression that is true for rows in reach, over the
+ * given location column, binding through `params`.
+ *
+ * `TRUE` for a caller who reaches everywhere, so the statement reads the same
+ * either way. Otherwise the locations go in as ONE comma-joined text parameter
+ * unpacked by `string_to_array` — a location id is a uuid or a slug and can
+ * never contain the separator. An empty list becomes an empty array, so a
+ * caller assigned nowhere matches nothing rather than everything: the two
+ * states are different values, not one sentinel doing double duty.
+ */
+declare function predicate(reach: Reach, column: string, params: unknown[]): string;
+/**
+ * The app-admin gate, decided in one place. `appRole` is derived by the
+ * platform (`Ring::AppAdmin`) and is the ONE field on `ctx.user` a function
+ * may gate on; `orgRole` and `teams` are there to explain, not to decide.
+ */
+declare function isAdmin(ctx: Pick<ReachCtx, "user">): boolean;
+declare function adminOnly(what: string): Response;
+//#endregion
+export { Reach, ReachCtx, adminOnly, isAdmin, predicate, reachOf, reaches, requireReach };
+//# sourceMappingURL=ops.d.cts.map

package/dist/ops.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.cts","names":[],"sources":["../src/ops/index.ts"],"mappings":";;;;KAsBY,QAAQ;;UAGH;EACf;;;;;;IAME,QAAQ;IACR;IACA;;;;;;;;;;;;;iBAgBY,QAAQ,KAAK,WAAW;iBAMxB,QAAQ,OAAO,OAAO;;;;;;;;;iBAYtB,aAAa,KAAK,UAAU,qBAAqB;;;;;;;;;;;;iBAmBjD,UAAU,OAAO,OAAO,gBAAgB;;;;;;iBAgBxC,QAAQ,KAAK,KAAK;iBAIlB,UAAU,eAAe"}

package/dist/ops.d.mts

@@ -0,0 +1,61 @@
+
+import { _ as OxyReach } from "./function-context-D8eyZuw_.mjs";
+//#region src/ops/index.d.ts
+/** What `ctx.user.reach` carries — one shape, declared once on the context type. */
+type Reach = OxyReach;
+/** The slice of `ctx` this module reads — a test hands in exactly this. */
+interface ReachCtx {
+  user: {
+    /**
+     * Present on every invocation since SDK 2.12 / the operating graph. Typed
+     * optional here so a function can be written before its server is
+     * upgraded: an absent reach is the fail-closed answer, never the office.
+     */
+    reach?: Reach | null;
+    appRole?: string;
+    kind?: string;
+  };
+}
+/**
+ * The caller's reach. Synchronous — the platform decided it before the
+ * function ran — but `await reachOf(ctx)` still works, so code written against
+ * the app-side version keeps compiling.
+ *
+ * Absent reach (an older server) lands on nowhere. Not "system reaches
+ * everywhere, everyone else nowhere": a system invocation on an older server
+ * carries no reach either, and the one thing this module must never do is
+ * invent a wider answer than the platform gave.
+ */
+declare function reachOf(ctx: ReachCtx): Reach;
+declare function reaches(reach: Reach, locationId: string): boolean;
+/**
+ * For a writer naming a location: the 403 to return, or null to proceed.
+ *
+ * The message names the location and not the roster, and the code is stable:
+ * the client tells "you are not rostered here" from "no such location" (a 404
+ * the writers answer BEFORE this) and from "admin only" (a 403 with another
+ * code) without parsing English.
+ */
+declare function requireReach(ctx: ReachCtx, locationId: string): Response | null;
+/**
+ * For a reader: a SQL expression that is true for rows in reach, over the
+ * given location column, binding through `params`.
+ *
+ * `TRUE` for a caller who reaches everywhere, so the statement reads the same
+ * either way. Otherwise the locations go in as ONE comma-joined text parameter
+ * unpacked by `string_to_array` — a location id is a uuid or a slug and can
+ * never contain the separator. An empty list becomes an empty array, so a
+ * caller assigned nowhere matches nothing rather than everything: the two
+ * states are different values, not one sentinel doing double duty.
+ */
+declare function predicate(reach: Reach, column: string, params: unknown[]): string;
+/**
+ * The app-admin gate, decided in one place. `appRole` is derived by the
+ * platform (`Ring::AppAdmin`) and is the ONE field on `ctx.user` a function
+ * may gate on; `orgRole` and `teams` are there to explain, not to decide.
+ */
+declare function isAdmin(ctx: Pick<ReachCtx, "user">): boolean;
+declare function adminOnly(what: string): Response;
+//#endregion
+export { Reach, ReachCtx, adminOnly, isAdmin, predicate, reachOf, reaches, requireReach };
+//# sourceMappingURL=ops.d.mts.map

package/dist/ops.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.mts","names":[],"sources":["../src/ops/index.ts"],"mappings":";;;;KAsBY,QAAQ;;UAGH;EACf;;;;;;IAME,QAAQ;IACR;IACA;;;;;;;;;;;;;iBAgBY,QAAQ,KAAK,WAAW;iBAMxB,QAAQ,OAAO,OAAO;;;;;;;;;iBAYtB,aAAa,KAAK,UAAU,qBAAqB;;;;;;;;;;;;iBAmBjD,UAAU,OAAO,OAAO,gBAAgB;;;;;;iBAgBxC,QAAQ,KAAK,KAAK;iBAIlB,UAAU,eAAe"}

package/dist/ops.mjs

@@ -0,0 +1,79 @@
+// @oxy/sdk - TypeScript SDK for Oxy data platform
+//#region src/ops/index.ts
+const NOWHERE = {
+	everywhere: false,
+	via: null,
+	locations: []
+};
+/**
+* The caller's reach. Synchronous — the platform decided it before the
+* function ran — but `await reachOf(ctx)` still works, so code written against
+* the app-side version keeps compiling.
+*
+* Absent reach (an older server) lands on nowhere. Not "system reaches
+* everywhere, everyone else nowhere": a system invocation on an older server
+* carries no reach either, and the one thing this module must never do is
+* invent a wider answer than the platform gave.
+*/
+function reachOf(ctx) {
+	const r = ctx.user.reach;
+	if (!r || typeof r !== "object" || !Array.isArray(r.locations)) return NOWHERE;
+	return {
+		everywhere: r.everywhere === true,
+		via: r.via ?? null,
+		locations: [...r.locations]
+	};
+}
+function reaches(reach, locationId) {
+	return reach.everywhere || reach.locations.includes(locationId);
+}
+/**
+* For a writer naming a location: the 403 to return, or null to proceed.
+*
+* The message names the location and not the roster, and the code is stable:
+* the client tells "you are not rostered here" from "no such location" (a 404
+* the writers answer BEFORE this) and from "admin only" (a 403 with another
+* code) without parsing English.
+*/
+function requireReach(ctx, locationId) {
+	if (reaches(reachOf(ctx), locationId)) return null;
+	return Response.json({
+		error: `you are not rostered at ${locationId}`,
+		code: "OutOfReach",
+		locationId
+	}, { status: 403 });
+}
+/**
+* For a reader: a SQL expression that is true for rows in reach, over the
+* given location column, binding through `params`.
+*
+* `TRUE` for a caller who reaches everywhere, so the statement reads the same
+* either way. Otherwise the locations go in as ONE comma-joined text parameter
+* unpacked by `string_to_array` — a location id is a uuid or a slug and can
+* never contain the separator. An empty list becomes an empty array, so a
+* caller assigned nowhere matches nothing rather than everything: the two
+* states are different values, not one sentinel doing double duty.
+*/
+function predicate(reach, column, params) {
+	if (reach.everywhere) return "TRUE";
+	params.push(reach.locations.join(","));
+	return `${column}::text = ANY(string_to_array($${params.length}::text, ','))`;
+}
+/**
+* The app-admin gate, decided in one place. `appRole` is derived by the
+* platform (`Ring::AppAdmin`) and is the ONE field on `ctx.user` a function
+* may gate on; `orgRole` and `teams` are there to explain, not to decide.
+*/
+function isAdmin(ctx) {
+	return (ctx.user.appRole ?? "") === "admin";
+}
+function adminOnly(what) {
+	return Response.json({
+		error: `${what} needs app-admin standing`,
+		code: "AdminOnly"
+	}, { status: 403 });
+}
+
+//#endregion
+export { adminOnly, isAdmin, predicate, reachOf, reaches, requireReach };
+//# sourceMappingURL=ops.mjs.map

package/dist/ops.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.mjs","names":[],"sources":["../src/ops/index.ts"],"sourcesContent":["// `@oxy-hq/sdk/ops` — the operating graph, applied inside an Oxy Function.\n//\n// The platform states where a caller may act (`ctx.user.reach`, derived from\n// their assignments — see `internal-docs/operating-graph.md` §3.3); this is\n// how a function applies it. Library code, versioned with the SDK, and\n// replaceable: an app that needs a tighter rule wraps `reachOf` and keeps the\n// rest. It may tighten, never widen — the reach the platform hands in is the\n// ceiling.\n//\n// Lifted from Store Ops's `functions/access.ts` (customer-apps #138) minus its\n// roster SQL: the roster is the platform's now, so the decision arrives on\n// `ctx.user` and nothing here reads a table.\n//\n// Two entry points. `requireReach` for a writer that names a location: the\n// 403 to return, or null. `predicate` for a reader: a SQL expression over the\n// statement's own location column, bound through the statement's parameter\n// list, so the scope lives in the WHERE — before the LIMIT, so a page is a\n// page of the right set.\n\nimport type { OxyReach } from \"../custom-app/function-context\";\n\n/** What `ctx.user.reach` carries — one shape, declared once on the context type. */\nexport type Reach = OxyReach;\n\n/** The slice of `ctx` this module reads — a test hands in exactly this. */\nexport interface ReachCtx {\n  user: {\n    /**\n     * Present on every invocation since SDK 2.12 / the operating graph. Typed\n     * optional here so a function can be written before its server is\n     * upgraded: an absent reach is the fail-closed answer, never the office.\n     */\n    reach?: Reach | null;\n    appRole?: string;\n    kind?: string;\n  };\n}\n\nconst NOWHERE: Reach = { everywhere: false, via: null, locations: [] };\n\n/**\n * The caller's reach. Synchronous — the platform decided it before the\n * function ran — but `await reachOf(ctx)` still works, so code written against\n * the app-side version keeps compiling.\n *\n * Absent reach (an older server) lands on nowhere. Not \"system reaches\n * everywhere, everyone else nowhere\": a system invocation on an older server\n * carries no reach either, and the one thing this module must never do is\n * invent a wider answer than the platform gave.\n */\nexport function reachOf(ctx: ReachCtx): Reach {\n  const r = ctx.user.reach;\n  if (!r || typeof r !== \"object\" || !Array.isArray(r.locations)) return NOWHERE;\n  return { everywhere: r.everywhere === true, via: r.via ?? null, locations: [...r.locations] };\n}\n\nexport function reaches(reach: Reach, locationId: string): boolean {\n  return reach.everywhere || reach.locations.includes(locationId);\n}\n\n/**\n * For a writer naming a location: the 403 to return, or null to proceed.\n *\n * The message names the location and not the roster, and the code is stable:\n * the client tells \"you are not rostered here\" from \"no such location\" (a 404\n * the writers answer BEFORE this) and from \"admin only\" (a 403 with another\n * code) without parsing English.\n */\nexport function requireReach(ctx: ReachCtx, locationId: string): Response | null {\n  if (reaches(reachOf(ctx), locationId)) return null;\n  return Response.json(\n    { error: `you are not rostered at ${locationId}`, code: \"OutOfReach\", locationId },\n    { status: 403 }\n  );\n}\n\n/**\n * For a reader: a SQL expression that is true for rows in reach, over the\n * given location column, binding through `params`.\n *\n * `TRUE` for a caller who reaches everywhere, so the statement reads the same\n * either way. Otherwise the locations go in as ONE comma-joined text parameter\n * unpacked by `string_to_array` — a location id is a uuid or a slug and can\n * never contain the separator. An empty list becomes an empty array, so a\n * caller assigned nowhere matches nothing rather than everything: the two\n * states are different values, not one sentinel doing double duty.\n */\nexport function predicate(reach: Reach, column: string, params: unknown[]): string {\n  if (reach.everywhere) return \"TRUE\";\n  params.push(reach.locations.join(\",\"));\n  // `::text` on the column: `string_to_array` yields `text[]`, and Postgres\n  // will not compare a `uuid` column to it on its own (`uuid = text` has no\n  // operator). The platform's location ids ARE uuids, so a tenant storing\n  // them in the natural column type would otherwise get a reader that never\n  // runs. A text column is unaffected.\n  return `${column}::text = ANY(string_to_array($${params.length}::text, ','))`;\n}\n\n/**\n * The app-admin gate, decided in one place. `appRole` is derived by the\n * platform (`Ring::AppAdmin`) and is the ONE field on `ctx.user` a function\n * may gate on; `orgRole` and `teams` are there to explain, not to decide.\n */\nexport function isAdmin(ctx: Pick<ReachCtx, \"user\">): boolean {\n  return (ctx.user.appRole ?? \"\") === \"admin\";\n}\n\nexport function adminOnly(what: string): Response {\n  return Response.json(\n    { error: `${what} needs app-admin standing`, code: \"AdminOnly\" },\n    { status: 403 }\n  );\n}\n"],"mappings":";;AAsCA,MAAM,UAAiB;CAAE,YAAY;CAAO,KAAK;CAAM,WAAW,CAAC;AAAE;;;;;;;;;;;AAYrE,SAAgB,QAAQ,KAAsB;CAC5C,MAAM,IAAI,IAAI,KAAK;CACnB,IAAI,CAAC,KAAK,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,EAAE,SAAS,GAAG,OAAO;CACvE,OAAO;EAAE,YAAY,EAAE,eAAe;EAAM,KAAK,EAAE,OAAO;EAAM,WAAW,CAAC,GAAG,EAAE,SAAS;CAAE;AAC9F;AAEA,SAAgB,QAAQ,OAAc,YAA6B;CACjE,OAAO,MAAM,cAAc,MAAM,UAAU,SAAS,UAAU;AAChE;;;;;;;;;AAUA,SAAgB,aAAa,KAAe,YAAqC;CAC/E,IAAI,QAAQ,QAAQ,GAAG,GAAG,UAAU,GAAG,OAAO;CAC9C,OAAO,SAAS,KACd;EAAE,OAAO,2BAA2B;EAAc,MAAM;EAAc;CAAW,GACjF,EAAE,QAAQ,IAAI,CAChB;AACF;;;;;;;;;;;;AAaA,SAAgB,UAAU,OAAc,QAAgB,QAA2B;CACjF,IAAI,MAAM,YAAY,OAAO;CAC7B,OAAO,KAAK,MAAM,UAAU,KAAK,GAAG,CAAC;CAMrC,OAAO,GAAG,OAAO,gCAAgC,OAAO,OAAO;AACjE;;;;;;AAOA,SAAgB,QAAQ,KAAsC;CAC5D,QAAQ,IAAI,KAAK,WAAW,QAAQ;AACtC;AAEA,SAAgB,UAAU,MAAwB;CAChD,OAAO,SAAS,KACd;EAAE,OAAO,GAAG,KAAK;EAA4B,MAAM;CAAY,GAC/D,EAAE,QAAQ,IAAI,CAChB;AACF"}

package/dist/{react-B7zt-0RH.mjs → react-BXGyzgz0.mjs}

@@ -772,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
@@ -946,7 +947,7 @@ function useFunction(name) {
 * inputs (e.g. a user-picked filter value) are available.
 */
 function useSemanticQuery(input, opts = {}) {
-	const { projectId, fetcher } = useOxyApp();
+	const { projectId, appId, fetcher } = useOxyApp();
 	const enabled = opts.enabled !== false;
 	const debug = opts.debug === true;
 	const inputKey = React.useMemo(() => JSON.stringify(input), [input]);
@@ -981,7 +982,11 @@ function useSemanticQuery(input, opts = {}) {
 			measures: input.measures ?? [],
 			time_dimensions: input.time_dimensions ?? [],
 			filters: input.filters ?? [],
-			...input.limit != null ? { limit: input.limit } : {}
+			...input.limit != null ? { limit: input.limit } : {},
+			...input.scope ? {
+				scope: input.scope,
+				...appId ? { app: appId } : {}
+			} : {}
 		});
 		const url = `/api/projects/${projectId}/semantic-query${debug ? "?debug=1" : ""}`;
 		fetcher(url, {
@@ -1019,6 +1024,7 @@ function useSemanticQuery(input, opts = {}) {
 	}, [
 		enabled,
 		projectId,
+		appId,
 		inputKey,
 		debug,
 		nonce,
@@ -1558,7 +1564,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(() => {
@@ -1569,7 +1575,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, {
@@ -1583,7 +1592,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();
@@ -2284,4 +2297,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-B7zt-0RH.mjs.map
+//# sourceMappingURL=react-BXGyzgz0.mjs.map