@oxy-hq/sdk 2.11.0 → 2.13.0

package/dist/{react-CLONxcnA.d.cts → react-D-Sf973d.d.cts}

@@ -23,6 +23,31 @@ interface OxyAppFunctionManifest {
     pipeline: string;
     resource: string;
   };
+  /**
+   * Receive an unauthenticated POST from a third party at
+   * `POST /api/webhooks/apps/<org>/<app>/<name>`.
+   *
+   * The PLATFORM verifies every request — HMAC-SHA256 over the raw body, in
+   * constant time — before the function is enqueued, so app code never sees an
+   * unverified request. Omit the block and that endpoint answers 404, as if it
+   * did not exist.
+   */
+  webhook?: {
+    /**
+     * App-secret key holding the signing key(s) — the same `apps/<app-id>/`
+     * namespace `ctx.env` reads. The manifest names the secret, never holds it.
+     *
+     * **Comma-separated for rotation.** Providers that keep two live signing
+     * keys (Uber's `BASIC_HMAC` does) sign with either during a rotation; any
+     * match passes, so adopting a new key does not drop the events still
+     * signed with the old one.
+     */
+    secretVar: string;
+    /** Header carrying the signature, e.g. `x-uber-signature`. */
+    signatureHeader: string;
+    /** How the digest is encoded. Default `hex`. */
+    encoding?: "hex" | "base64";
+  };
   /** Wall-clock timeout. Default 30, max 300. */
   timeoutSeconds?: number;
   /**
@@ -187,6 +212,37 @@ interface OxyAppManifest {
     agent?: string;
     suggestedQuestions?: string[];
   };
+  /**
+   * The secrets this app expects, keyed by env-var name — the app's
+   * `.env.example`, declared rather than written in a README.
+   *
+   * These are the keys your functions read as `ctx.env.KEY`. Declaring one puts
+   * it in the app's Secrets surface (staff console → app → Secrets, and the
+   * workspace's own settings) as a row to fill in, so a fresh deploy says what
+   * is still missing instead of failing at the first invocation. Every function's
+   * `webhook.secretVar` is folded in automatically — no need to repeat it here.
+   *
+   * **Names only, never values.** A manifest ships inside the bundle and is
+   * fetchable over the app's own host; putting a secret in one publishes it.
+   * Values are set out-of-band on the Secrets surface, or by
+   * `ctx.secrets.set` from a function holding the `secrets.write` capability.
+   *
+   * App-level rather than per-function, because a secret is app-scoped by
+   * construction: two functions sharing `STRIPE_API_KEY` read the same value,
+   * so it can only be described once.
+   *
+   * ```jsonc
+   * "env": {
+   *   "STRIPE_API_KEY":    { "required": true, "description": "Restricted key, Dashboard → Developers" },
+   *   "SLACK_WEBHOOK_URL": { "description": "Optional ops channel" }
+   * }
+   * ```
+   *
+   * Read by the platform at **publish time** (like {@link OxyAppStorageManifest}),
+   * so the block is documented here but not round-tripped through the dev-time
+   * manifest fetch.
+   */
+  env?: Record<string, OxyAppEnvDeclaration>;
   /**
    * Optional app-level storage policy. Distinct from the per-function
    * `storage: { read, write }` capability: those gate what one function may
@@ -220,6 +276,24 @@ interface OxyAppManifest {
    */
   analytics?: boolean;
 }
+/** One declared secret — an entry in the `env` block of `oxy-app.json`. */
+interface OxyAppEnvDeclaration {
+  /**
+   * Flag the key as **Missing** (rather than merely absent) while nothing is
+   * stored for it, and count it in the app's missing-secrets badge.
+   *
+   * Advisory, not a gate: a publish is never blocked on an unset key, because
+   * the first publish is exactly when nobody could have set one yet.
+   *
+   * Default: `false` — a declaration is documentation first.
+   */
+  required?: boolean;
+  /**
+   * Shown beside the key on the Secrets surface. Say what it is and where to
+   * get one — this is the text that saves someone a Slack message.
+   */
+  description?: string;
+}
 /** Browser-runtime performance opt-outs — the `performance` block in `oxy-app.json`. */
 interface OxyAppPerformanceManifest {
   /**
@@ -387,6 +461,14 @@ type FunctionError = Error & {
   logs?: FunctionLog[];
   status?: number;
   body?: unknown;
+  /**
+   * The platform trace this invoke ran in (32 hex chars) and the server-minted
+   * `x-oxy-request-id`, when the request got as far as the server. Quote
+   * either in a bug report: an operator can open the trace in HyperDX, and
+   * an app admin can filter the app's Logs by the request.
+   */
+  traceId?: string;
+  requestId?: string;
 };
 //#endregion
 //#region src/custom-app/react.d.ts
@@ -509,7 +591,10 @@ interface UseFunctionResult<Data = unknown> {
   data: Data | null;
   /** True while an invocation is in flight. */
   isLoading: boolean;
-  /** Last invocation error, or null. On error this carries `.logs` too. */
+  /**
+   * Last invocation error, or null. On error this carries `.logs`, and
+   * `.traceId` / `.requestId` — the ids that name the run to an operator.
+   */
   error: Error | null;
   /**
    * `console.*` / `ctx.log` output from the last invoke (success or error), so
@@ -569,6 +654,13 @@ interface UseSemanticQueryInput {
   time_dimensions?: SemanticTimeDimension[];
   filters?: SemanticFilter[];
   limit?: number;
+  /**
+   * `"reach"` — pin the query server-side to the viewer's places: one `in`
+   * filter per view it names whose primary entity is bound to the org's
+   * locations registry. The bundle's own app is sent along so app-admin
+   * standing counts. A query naming no bound view is refused.
+   */
+  scope?: "reach";
 }
 interface UseSemanticQueryOpts {
   /** Set false to skip the request (e.g., waiting on user input). */
@@ -829,4 +921,4 @@ interface OxyChatProps {
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
 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.cts.map
+//# sourceMappingURL=react-D-Sf973d.d.cts.map

package/dist/react-D-Sf973d.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-D-Sf973d.d.cts","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-CLONxcnA.d.mts → react-D-Sf973d.d.mts}

@@ -23,6 +23,31 @@ interface OxyAppFunctionManifest {
     pipeline: string;
     resource: string;
   };
+  /**
+   * Receive an unauthenticated POST from a third party at
+   * `POST /api/webhooks/apps/<org>/<app>/<name>`.
+   *
+   * The PLATFORM verifies every request — HMAC-SHA256 over the raw body, in
+   * constant time — before the function is enqueued, so app code never sees an
+   * unverified request. Omit the block and that endpoint answers 404, as if it
+   * did not exist.
+   */
+  webhook?: {
+    /**
+     * App-secret key holding the signing key(s) — the same `apps/<app-id>/`
+     * namespace `ctx.env` reads. The manifest names the secret, never holds it.
+     *
+     * **Comma-separated for rotation.** Providers that keep two live signing
+     * keys (Uber's `BASIC_HMAC` does) sign with either during a rotation; any
+     * match passes, so adopting a new key does not drop the events still
+     * signed with the old one.
+     */
+    secretVar: string;
+    /** Header carrying the signature, e.g. `x-uber-signature`. */
+    signatureHeader: string;
+    /** How the digest is encoded. Default `hex`. */
+    encoding?: "hex" | "base64";
+  };
   /** Wall-clock timeout. Default 30, max 300. */
   timeoutSeconds?: number;
   /**
@@ -187,6 +212,37 @@ interface OxyAppManifest {
     agent?: string;
     suggestedQuestions?: string[];
   };
+  /**
+   * The secrets this app expects, keyed by env-var name — the app's
+   * `.env.example`, declared rather than written in a README.
+   *
+   * These are the keys your functions read as `ctx.env.KEY`. Declaring one puts
+   * it in the app's Secrets surface (staff console → app → Secrets, and the
+   * workspace's own settings) as a row to fill in, so a fresh deploy says what
+   * is still missing instead of failing at the first invocation. Every function's
+   * `webhook.secretVar` is folded in automatically — no need to repeat it here.
+   *
+   * **Names only, never values.** A manifest ships inside the bundle and is
+   * fetchable over the app's own host; putting a secret in one publishes it.
+   * Values are set out-of-band on the Secrets surface, or by
+   * `ctx.secrets.set` from a function holding the `secrets.write` capability.
+   *
+   * App-level rather than per-function, because a secret is app-scoped by
+   * construction: two functions sharing `STRIPE_API_KEY` read the same value,
+   * so it can only be described once.
+   *
+   * ```jsonc
+   * "env": {
+   *   "STRIPE_API_KEY":    { "required": true, "description": "Restricted key, Dashboard → Developers" },
+   *   "SLACK_WEBHOOK_URL": { "description": "Optional ops channel" }
+   * }
+   * ```
+   *
+   * Read by the platform at **publish time** (like {@link OxyAppStorageManifest}),
+   * so the block is documented here but not round-tripped through the dev-time
+   * manifest fetch.
+   */
+  env?: Record<string, OxyAppEnvDeclaration>;
   /**
    * Optional app-level storage policy. Distinct from the per-function
    * `storage: { read, write }` capability: those gate what one function may
@@ -220,6 +276,24 @@ interface OxyAppManifest {
    */
   analytics?: boolean;
 }
+/** One declared secret — an entry in the `env` block of `oxy-app.json`. */
+interface OxyAppEnvDeclaration {
+  /**
+   * Flag the key as **Missing** (rather than merely absent) while nothing is
+   * stored for it, and count it in the app's missing-secrets badge.
+   *
+   * Advisory, not a gate: a publish is never blocked on an unset key, because
+   * the first publish is exactly when nobody could have set one yet.
+   *
+   * Default: `false` — a declaration is documentation first.
+   */
+  required?: boolean;
+  /**
+   * Shown beside the key on the Secrets surface. Say what it is and where to
+   * get one — this is the text that saves someone a Slack message.
+   */
+  description?: string;
+}
 /** Browser-runtime performance opt-outs — the `performance` block in `oxy-app.json`. */
 interface OxyAppPerformanceManifest {
   /**
@@ -387,6 +461,14 @@ type FunctionError = Error & {
   logs?: FunctionLog[];
   status?: number;
   body?: unknown;
+  /**
+   * The platform trace this invoke ran in (32 hex chars) and the server-minted
+   * `x-oxy-request-id`, when the request got as far as the server. Quote
+   * either in a bug report: an operator can open the trace in HyperDX, and
+   * an app admin can filter the app's Logs by the request.
+   */
+  traceId?: string;
+  requestId?: string;
 };
 //#endregion
 //#region src/custom-app/react.d.ts
@@ -509,7 +591,10 @@ interface UseFunctionResult<Data = unknown> {
   data: Data | null;
   /** True while an invocation is in flight. */
   isLoading: boolean;
-  /** Last invocation error, or null. On error this carries `.logs` too. */
+  /**
+   * Last invocation error, or null. On error this carries `.logs`, and
+   * `.traceId` / `.requestId` — the ids that name the run to an operator.
+   */
   error: Error | null;
   /**
    * `console.*` / `ctx.log` output from the last invoke (success or error), so
@@ -569,6 +654,13 @@ interface UseSemanticQueryInput {
   time_dimensions?: SemanticTimeDimension[];
   filters?: SemanticFilter[];
   limit?: number;
+  /**
+   * `"reach"` — pin the query server-side to the viewer's places: one `in`
+   * filter per view it names whose primary entity is bound to the org's
+   * locations registry. The bundle's own app is sent along so app-admin
+   * standing counts. A query naming no bound view is refused.
+   */
+  scope?: "reach";
 }
 interface UseSemanticQueryOpts {
   /** Set false to skip the request (e.g., waiting on user input). */
@@ -829,4 +921,4 @@ interface OxyChatProps {
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
 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
+//# sourceMappingURL=react-D-Sf973d.d.mts.map

package/dist/react-D-Sf973d.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-D-Sf973d.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/shell.cjs

@@ -1,6 +1,6 @@
 // @oxy/sdk - TypeScript SDK for Oxy data platform
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_react = require('./react-riTxd9ce.cjs');
+const require_react = require('./react-CkAQg9wB.cjs');
 let react = require("react");
 react = require_react.__toESM(react, 1);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -1787,7 +1787,7 @@ function ShellRail({ top, groups, footerItems, bottom, className }) {
 * endpoint), so errors are surfaced on the result, never thrown.
 */
 function useShellContext() {
-	const { projectId, fetcher } = require_react.useOxyApp();
+	const { projectId, appId, fetcher } = require_react.useOxyApp();
 	const [state, setState] = react.useState({
 		data: null,
 		loading: true,
@@ -1803,7 +1803,8 @@ function useShellContext() {
 			return;
 		}
 		let cancelled = false;
-		fetcher(`/api/projects/${projectId}/shell-context`, { method: "GET" }).then(async (resp) => {
+		const query = appId ? `?app=${encodeURIComponent(appId)}` : "";
+		fetcher(`/api/projects/${projectId}/shell-context${query}`, { method: "GET" }).then(async (resp) => {
 			if (!resp.ok) throw new Error(`shell-context failed: HTTP ${resp.status}`);
 			const data = await resp.json();
 			if (!cancelled) setState({
@@ -1823,9 +1824,69 @@ function useShellContext() {
 		return () => {
 			cancelled = true;
 		};
-	}, [projectId, fetcher]);
+	}, [
+		projectId,
+		appId,
+		fetcher
+	]);
 	return state;
 }
+const NOWHERE = {
+	everywhere: false,
+	via: null,
+	locations: []
+};
+/**
+* The viewer, in one shape, on every server version: who is signed in, the
+* crew-or-office signal, and where they work — for a greeting, a "your
+* store" default, or hiding a tab. Never for authorization: a browser can
+* edit what it renders, and the function's `ctx.user.reach` is the gate.
+*/
+function useIdentity() {
+	const { data, loading } = useShellContext();
+	const u = data?.user ?? null;
+	return {
+		id: u?.id ?? null,
+		name: u?.name ?? "",
+		email: u?.email ? u.email : null,
+		picture: u?.picture ?? null,
+		kind: u?.kind ?? null,
+		reach: u?.reach ?? NOWHERE,
+		loading
+	};
+}
+/**
+* Where a signed-out person lands: the product's login page, with this app
+* as the place to come back to.
+*
+* `loginUrl` is `links.login` from the shell context — the product host's,
+* which a custom-app subdomain cannot derive — and `/login` on the current
+* origin when the context is unavailable or the server predates the field.
+* `returnTo` is the app's own address, which it knows legitimately.
+*/
+function signOutUrl(loginUrl, returnTo) {
+	const base = loginUrl?.trim() ? loginUrl.trim() : "/login";
+	return `${base}${base.includes("?") ? "&" : "?"}return_to=${encodeURIComponent(returnTo)}`;
+}
+/**
+* End the platform session, then leave for the login page.
+*
+* `GET /api/logout` clears the session cookie server-side. That is the same
+* cookie a crew member's PIN session rides, so on an enrolled tablet the login
+* page comes back as "Who's on shift?" and returns to the app after the next
+* PIN; elsewhere it is the ordinary sign-in. Throws when the server refused,
+* so a caller can say so rather than navigate away from a session that still
+* exists. Pass the app's `fetcher` from `useOxyApp()` so credentials ride.
+*/
+async function signOut(fetcher, loginUrl, returnTo) {
+	const res = await fetcher("/api/logout", {
+		method: "GET",
+		credentials: "include"
+	});
+	if (!res.ok) throw new Error(`sign-out refused: HTTP ${res.status}`);
+	if (typeof window === "undefined") return;
+	window.location.assign(signOutUrl(loginUrl, returnTo ?? window.location.href));
+}
 
 //#endregion
 //#region src/shell/TopBar.tsx
@@ -2168,6 +2229,9 @@ exports.WorkspaceClock = WorkspaceClock;
 exports.WorkspaceTile = WorkspaceTile;
 exports.buildTraceSteps = buildTraceSteps;
 exports.fetchThreadTranscript = fetchThreadTranscript;
+exports.signOut = signOut;
+exports.signOutUrl = signOutUrl;
+exports.useIdentity = useIdentity;
 exports.useShellContext = useShellContext;
 exports.useThreadHistory = useThreadHistory;
 exports.workspaceLogoUrl = workspaceLogoUrl;