@oxy-hq/sdk 2.11.0 → 2.13.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-riTxd9ce.cjs → react-CkAQg9wB.cjs}

@@ -392,10 +392,25 @@ function validateFunctions(raw) {
 			}
 			fn.retries = retries;
 		}
+		if (value.webhook !== void 0) {
+			const w = value.webhook;
+			if (!isRecord(w)) throw new Error(`oxy-app.json: function "${fnName}" \`webhook\` must be an object`);
+			for (const key of ["secretVar", "signatureHeader"]) if (typeof w[key] !== "string" || !w[key].trim()) throw new Error(`oxy-app.json: function "${fnName}" \`webhook.${key}\` must be a non-empty string`);
+			const webhook = {
+				secretVar: w.secretVar,
+				signatureHeader: w.signatureHeader
+			};
+			if (w.encoding !== void 0) {
+				if (w.encoding !== "hex" && w.encoding !== "base64") throw new Error(`oxy-app.json: function "${fnName}" \`webhook.encoding\` must be "hex" or "base64"`);
+				webhook.encoding = w.encoding;
+			}
+			fn.webhook = webhook;
+		}
 		if (value.inputExample !== void 0) fn.inputExample = value.inputExample;
 		const hasSchedule = fn.schedule !== void 0;
 		const hasAirway = fn.airwayStep !== void 0;
-		if (!(fn.route ?? !(hasSchedule || hasAirway)) && !hasSchedule && !hasAirway) throw new Error(`oxy-app.json: function "${fnName}" must enable at least one of route/schedule/airwayStep`);
+		const hasWebhook = fn.webhook !== void 0;
+		if (!(fn.route ?? !(hasSchedule || hasAirway || hasWebhook)) && !hasSchedule && !hasAirway && !hasWebhook) throw new Error(`oxy-app.json: function "${fnName}" must enable at least one of route/schedule/airwayStep/webhook`);
 		out[fnName] = fn;
 	}
 	return out;
@@ -649,6 +664,44 @@ async function sharedQuery(fetcher, projectId, sql, db, opts = {}) {
 	return p;
 }
 
+//#endregion
+//#region src/custom-app/traceparent.ts
+const HEX = "0123456789abcdef";
+function randomHex(bytes) {
+	const buf = new Uint8Array(bytes);
+	const c = globalThis.crypto;
+	if (c && typeof c.getRandomValues === "function") c.getRandomValues(buf);
+	else for (let i = 0; i < bytes; i++) buf[i] = Math.floor(Math.random() * 256);
+	let out = "";
+	for (let i = 0; i < bytes; i++) out += HEX[buf[i] >> 4] + HEX[buf[i] & 15];
+	return out;
+}
+/** Mint a fresh, sampled `traceparent`. All-zero ids are invalid per the spec;
+*  the loop guards the astronomically unlikely draw. */
+function newTraceparent() {
+	let traceId = randomHex(16);
+	while (/^0+$/.test(traceId)) traceId = randomHex(16);
+	let spanId = randomHex(8);
+	while (/^0+$/.test(spanId)) spanId = randomHex(8);
+	return {
+		header: `00-${traceId}-${spanId}-01`,
+		traceId
+	};
+}
+/**
+* Stamp the ids of a failed invoke onto whatever was thrown, so the app (and
+* the platform's error beacon, which reads `traceId`) can name the trace and
+* the server-minted request id. Non-objects are returned untouched.
+*/
+function withInvocationIds(err, traceId, requestId) {
+	if (err && typeof err === "object") {
+		const target = err;
+		if (!target.traceId) target.traceId = traceId;
+		if (requestId && !target.requestId) target.requestId = requestId;
+	}
+	return err;
+}
+
 //#endregion
 //#region src/custom-app/react.tsx
 function defaultFetcher(input, init) {
@@ -921,9 +974,11 @@ function useFunction(name) {
 				error: null
 			}));
 			try {
+				const trace = newTraceparent();
 				const headers = {
 					"content-type": "application/json",
-					accept: "text/event-stream"
+					accept: "text/event-stream",
+					traceparent: trace.header
 				};
 				if (opts?.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
 				const result = await sharedFunctionInvoke(functionInvokeKey(name, body), async () => {
@@ -932,8 +987,13 @@ function useFunction(name) {
 						headers,
 						body: JSON.stringify(body ?? {})
 					});
-					if (!resp.ok && resp.status !== 200) throw await apiErrorFromResponse(resp);
-					return readFunctionSseStream(resp);
+					const requestId = resp.headers?.get?.("x-oxy-request-id") ?? null;
+					if (!resp.ok && resp.status !== 200) throw withInvocationIds(await apiErrorFromResponse(resp), trace.traceId, requestId);
+					try {
+						return await readFunctionSseStream(resp);
+					} catch (err) {
+						throw withInvocationIds(err, trace.traceId, requestId);
+					}
 				});
 				setState({
 					data: result.value,
@@ -975,7 +1035,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]);
@@ -1010,7 +1070,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, {
@@ -1048,6 +1112,7 @@ function useSemanticQuery(input, opts = {}) {
 	}, [
 		enabled,
 		projectId,
+		appId,
 		inputKey,
 		debug,
 		nonce,
@@ -2439,4 +2504,4 @@ Object.defineProperty(exports, 'useTrackEvent', {
     return useTrackEvent;
   }
 });
-//# sourceMappingURL=react-riTxd9ce.cjs.map
+//# sourceMappingURL=react-CkAQg9wB.cjs.map