@athenaintel/react 0.57.2 → 0.60.0

package/dist/data/use-athena-graphql.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const reactQuery = require("@tanstack/react-query");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const athenaApiError = require("./athena-api-error.cjs");
+const athenaDataClient = require("./athena-data-client.cjs");
+const athenaRequest = require("./athena-request.cjs");
+function useAthenaGraphQL(document, variables, options = {}) {
+  const config = AthenaContext.useAthenaConfig();
+  const scope = athenaDataClient.useAthenaDataScope();
+  const client = athenaDataClient.useAthenaDataQueryClient();
+  const { operationName, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;
+  const text = String(document);
+  return reactQuery.useQuery(
+    {
+      retry: athenaDataClient.retryAthenaRead,
+      retryDelay: athenaDataClient.athenaRetryDelay,
+      staleTime: athenaDataClient.ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, athenaDataClient.AthenaDataKind.GraphQL, text, variables ?? {}, operationName ?? null],
+      queryFn: ({ signal }) => {
+        var _a;
+        if (((_a = athenaRequest.selectedGraphQLOperation(text, operationName)) == null ? void 0 : _a.type) !== "query") {
+          throw new athenaApiError.AthenaApiError({
+            kind: athenaApiError.AthenaApiErrorKind.Request,
+            message: "useAthenaGraphQL runs one query: name it with operationName when the document holds several, and send a mutation with useAthenaGraphQLMutation",
+            method: "POST",
+            path: "/graphql"
+          });
+        }
+        return athenaRequest.athenaGraphQL(config, text, variables, {
+          operationName,
+          timeoutMs,
+          rateLimitRetry,
+          headers,
+          signal
+        });
+      },
+      enabled: athenaDataClient.enabledAnd(enabled, config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+function useAthenaGraphQLMutation(document, options = {}) {
+  const config = AthenaContext.useAthenaConfig();
+  const client = athenaDataClient.useAthenaDataQueryClient();
+  const { operationName, timeoutMs, rateLimitRetry, headers, ...mutationOptions } = options;
+  const text = String(document);
+  return reactQuery.useMutation(
+    {
+      ...mutationOptions,
+      // TODO(#54756): send an Idempotency-Key per call once agora honours one, so
+      // a write sent twice (a retry, a double click) applies once.
+      mutationFn: (variables) => athenaRequest.athenaGraphQL(config, text, variables, {
+        operationName,
+        timeoutMs,
+        rateLimitRetry,
+        headers
+      })
+    },
+    client
+  );
+}
+exports.useAthenaGraphQL = useAthenaGraphQL;
+exports.useAthenaGraphQLMutation = useAthenaGraphQLMutation;
+//# sourceMappingURL=use-athena-graphql.cjs.map

package/dist/data/use-athena-graphql.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-graphql.cjs","sources":["../../src/data/use-athena-graphql.ts"],"sourcesContent":["/**\n * GraphQL on agora through TanStack Query, on the SDK's own client: a read\n * (`useAthenaGraphQL`) cached per identity and cancelled when its last reader\n * unmounts, and a write (`useAthenaGraphQLMutation`). Both run on the SDK's\n * transport (`athenaGraphQL`), so a read and a write carry the provider's\n * credential and fail as an `AthenaApiError`.\n */\nimport {\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n  useMutation,\n  useQuery,\n} from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { AthenaApiError, AthenaApiErrorKind } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport {\n  type AthenaGraphQLDocument,\n  type AthenaGraphQLRequestOptions,\n  type AthenaGraphQLVariables,\n  athenaGraphQL,\n  selectedGraphQLOperation,\n} from './athena-request';\n\n/** Request options of a GraphQL hook (its `signal` is TanStack Query's). */\nexport type AthenaGraphQLHookRequestOptions = Omit<AthenaGraphQLRequestOptions, 'signal'>;\n\n/**\n * `useAthenaGraphQL`'s options: TanStack Query's (`enabled`, `select`,\n * `staleTime`, `refetchInterval`…) and the request's (`timeoutMs`,\n * `rateLimitRetry`, `operationName`, `headers`).\n */\nexport type UseAthenaGraphQLOptions<TData, TSelected = TData> = Omit<\n  UseQueryOptions<TData, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  AthenaGraphQLHookRequestOptions;\n\n/**\n * Read with one GraphQL query on agora's `/graphql`, as the signed-in person.\n * Keyed by the identity (see `useAthenaDataScope`), the document and its\n * variables. Never retried on a 4xx or a GraphQL error; a failure with no\n * answer or a 5xx is asked twice more. Cancelled when no component reads it\n * any more. A mutation is refused here (it would run again on every refetch):\n * send it with `useAthenaGraphQLMutation`.\n *\n * ```tsx\n * const { data, error } = useAthenaGraphQL<{ asset: { title: string } }, { id: string }>(\n *   `query Asset($id: String!) { asset(id: $id) { title } }`,\n *   { id },\n * );\n * ```\n */\nexport function useAthenaGraphQL<\n  TData = unknown,\n  TVariables extends object = AthenaGraphQLVariables,\n  TSelected = TData,\n>(\n  document: AthenaGraphQLDocument<TData, TVariables>,\n  variables?: TVariables,\n  options: UseAthenaGraphQLOptions<TData, TSelected> = {},\n): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  const { operationName, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;\n  const text = String(document);\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.GraphQL, text, variables ?? {}, operationName ?? null],\n      queryFn: ({ signal }) => {\n        // The operation agora would run (`operationName`'s, else the only\n        // one), never just the document's first: a mutation or subscription\n        // here would run again on every refetch.\n        if (selectedGraphQLOperation(text, operationName)?.type !== 'query') {\n          throw new AthenaApiError({\n            kind: AthenaApiErrorKind.Request,\n            message:\n              'useAthenaGraphQL runs one query: name it with operationName when the document holds several, and send a mutation with useAthenaGraphQLMutation',\n            method: 'POST',\n            path: '/graphql',\n          });\n        }\n        return athenaGraphQL<TData, TVariables>(config, text, variables, {\n          operationName,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n          signal,\n        });\n      },\n      enabled: enabledAnd(enabled, config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n\n/**\n * `useAthenaGraphQLMutation`'s options: TanStack Query's mutation options\n * (`onSuccess`, `onError`, `onMutate`…) and the request's.\n */\nexport type UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult = unknown> = Omit<\n  UseMutationOptions<TData, AthenaApiError, TVariables, TOnMutateResult>,\n  'mutationFn'\n> &\n  AthenaGraphQLHookRequestOptions;\n\n/**\n * Write with one GraphQL mutation on agora's `/graphql`, as the signed-in\n * person: `mutate(variables)` / `mutateAsync(variables)`. Never retried (a 429\n * from agora's limiter is waited out by the transport: it refuses before\n * anything runs). A write already sent is not cancelled when its component\n * unmounts, since agora may have applied it; `timeoutMs` still bounds it.\n * Read the reads it changes again with `useInvalidateAthenaQueries`.\n *\n * ```tsx\n * const invalidate = useInvalidateAthenaQueries();\n * const rename = useAthenaGraphQLMutation<RenameResult, { id: string; title: string }>(RENAME, {\n *   onSuccess: () => invalidate({ operationNames: ['Asset'] }),\n * });\n * rename.mutate({ id, title });\n * ```\n */\nexport function useAthenaGraphQLMutation<\n  TData = unknown,\n  TVariables extends object = AthenaGraphQLVariables,\n  TOnMutateResult = unknown,\n>(\n  document: AthenaGraphQLDocument<TData, TVariables>,\n  options: UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult> = {},\n): UseMutationResult<TData, AthenaApiError, TVariables, TOnMutateResult> {\n  const config = useAthenaConfig();\n  const client = useAthenaDataQueryClient();\n  const { operationName, timeoutMs, rateLimitRetry, headers, ...mutationOptions } = options;\n  const text = String(document);\n  return useMutation(\n    {\n      ...mutationOptions,\n      // TODO(#54756): send an Idempotency-Key per call once agora honours one, so\n      // a write sent twice (a retry, a double click) applies once.\n      mutationFn: (variables: TVariables) =>\n        athenaGraphQL<TData, TVariables>(config, text, variables, {\n          operationName,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n        }),\n    },\n    client,\n  );\n}\n"],"names":["useAthenaConfig","useAthenaDataScope","useAthenaDataQueryClient","useQuery","retryAthenaRead","athenaRetryDelay","ATHENA_DATA_STALE_MS","AthenaDataKind","selectedGraphQLOperation","AthenaApiError","AthenaApiErrorKind","athenaGraphQL","enabledAnd","useMutation"],"mappings":";;;;;;;AA+DO,SAAS,iBAKd,UACA,WACA,UAAqD,CAAA,GACV;AAC3C,QAAM,SAASA,cAAAA,gBAAA;AACf,QAAM,QAAQC,iBAAAA,mBAAA;AACd,QAAM,SAASC,iBAAAA,yBAAA;AACf,QAAM,EAAE,eAAe,WAAW,gBAAgB,SAAS,SAAS,GAAG,iBAAiB;AACxF,QAAM,OAAO,OAAO,QAAQ;AAC5B,SAAOC,WAAAA;AAAAA,IACL;AAAA,MACE,OAAOC,iBAAAA;AAAAA,MACP,YAAYC,iBAAAA;AAAAA,MACZ,WAAWC,iBAAAA;AAAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAOC,gCAAe,SAAS,MAAM,aAAa,CAAA,GAAI,iBAAiB,IAAI;AAAA,MACzF,SAAS,CAAC,EAAE,aAAa;;AAIvB,cAAIC,mBAAAA,yBAAyB,MAAM,aAAa,MAA5CA,mBAA+C,UAAS,SAAS;AACnE,gBAAM,IAAIC,eAAAA,eAAe;AAAA,YACvB,MAAMC,eAAAA,mBAAmB;AAAA,YACzB,SACE;AAAA,YACF,QAAQ;AAAA,YACR,MAAM;AAAA,UAAA,CACP;AAAA,QACH;AACA,eAAOC,4BAAiC,QAAQ,MAAM,WAAW;AAAA,UAC/D;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,MACA,SAASC,iBAAAA,WAAW,SAAS,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAE3D;AAAA,EAAA;AAEJ;AA4BO,SAAS,yBAKd,UACA,UAA+E,IACR;AACvE,QAAM,SAASZ,cAAAA,gBAAA;AACf,QAAM,SAASE,iBAAAA,yBAAA;AACf,QAAM,EAAE,eAAe,WAAW,gBAAgB,SAAS,GAAG,oBAAoB;AAClF,QAAM,OAAO,OAAO,QAAQ;AAC5B,SAAOW,WAAAA;AAAAA,IACL;AAAA,MACE,GAAG;AAAA;AAAA;AAAA,MAGH,YAAY,CAAC,cACXF,cAAAA,cAAiC,QAAQ,MAAM,WAAW;AAAA,QACxD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,IAAA;AAAA,IAEL;AAAA,EAAA;AAEJ;;;"}

package/dist/data/use-athena-graphql.d.ts

@@ -0,0 +1,56 @@
+/**
+ * GraphQL on agora through TanStack Query, on the SDK's own client: a read
+ * (`useAthenaGraphQL`) cached per identity and cancelled when its last reader
+ * unmounts, and a write (`useAthenaGraphQLMutation`). Both run on the SDK's
+ * transport (`athenaGraphQL`), so a read and a write carry the provider's
+ * credential and fail as an `AthenaApiError`.
+ */
+import { type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import { AthenaApiError } from './athena-api-error';
+import { type AthenaGraphQLDocument, type AthenaGraphQLRequestOptions, type AthenaGraphQLVariables } from './athena-request';
+/** Request options of a GraphQL hook (its `signal` is TanStack Query's). */
+export type AthenaGraphQLHookRequestOptions = Omit<AthenaGraphQLRequestOptions, 'signal'>;
+/**
+ * `useAthenaGraphQL`'s options: TanStack Query's (`enabled`, `select`,
+ * `staleTime`, `refetchInterval`…) and the request's (`timeoutMs`,
+ * `rateLimitRetry`, `operationName`, `headers`).
+ */
+export type UseAthenaGraphQLOptions<TData, TSelected = TData> = Omit<UseQueryOptions<TData, AthenaApiError, TSelected>, 'queryKey' | 'queryFn'> & AthenaGraphQLHookRequestOptions;
+/**
+ * Read with one GraphQL query on agora's `/graphql`, as the signed-in person.
+ * Keyed by the identity (see `useAthenaDataScope`), the document and its
+ * variables. Never retried on a 4xx or a GraphQL error; a failure with no
+ * answer or a 5xx is asked twice more. Cancelled when no component reads it
+ * any more. A mutation is refused here (it would run again on every refetch):
+ * send it with `useAthenaGraphQLMutation`.
+ *
+ * ```tsx
+ * const { data, error } = useAthenaGraphQL<{ asset: { title: string } }, { id: string }>(
+ *   `query Asset($id: String!) { asset(id: $id) { title } }`,
+ *   { id },
+ * );
+ * ```
+ */
+export declare function useAthenaGraphQL<TData = unknown, TVariables extends object = AthenaGraphQLVariables, TSelected = TData>(document: AthenaGraphQLDocument<TData, TVariables>, variables?: TVariables, options?: UseAthenaGraphQLOptions<TData, TSelected>): UseQueryResult<TSelected, AthenaApiError>;
+/**
+ * `useAthenaGraphQLMutation`'s options: TanStack Query's mutation options
+ * (`onSuccess`, `onError`, `onMutate`…) and the request's.
+ */
+export type UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult = unknown> = Omit<UseMutationOptions<TData, AthenaApiError, TVariables, TOnMutateResult>, 'mutationFn'> & AthenaGraphQLHookRequestOptions;
+/**
+ * Write with one GraphQL mutation on agora's `/graphql`, as the signed-in
+ * person: `mutate(variables)` / `mutateAsync(variables)`. Never retried (a 429
+ * from agora's limiter is waited out by the transport: it refuses before
+ * anything runs). A write already sent is not cancelled when its component
+ * unmounts, since agora may have applied it; `timeoutMs` still bounds it.
+ * Read the reads it changes again with `useInvalidateAthenaQueries`.
+ *
+ * ```tsx
+ * const invalidate = useInvalidateAthenaQueries();
+ * const rename = useAthenaGraphQLMutation<RenameResult, { id: string; title: string }>(RENAME, {
+ *   onSuccess: () => invalidate({ operationNames: ['Asset'] }),
+ * });
+ * rename.mutate({ id, title });
+ * ```
+ */
+export declare function useAthenaGraphQLMutation<TData = unknown, TVariables extends object = AthenaGraphQLVariables, TOnMutateResult = unknown>(document: AthenaGraphQLDocument<TData, TVariables>, options?: UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult>): UseMutationResult<TData, AthenaApiError, TVariables, TOnMutateResult>;

package/dist/data/use-athena-graphql.js

@@ -0,0 +1,66 @@
+import { useQuery, useMutation } from "@tanstack/react-query";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { AthenaApiError, AthenaApiErrorKind } from "./athena-api-error.js";
+import { useAthenaDataScope, useAthenaDataQueryClient, AthenaDataKind, ATHENA_DATA_STALE_MS, athenaRetryDelay, retryAthenaRead, enabledAnd } from "./athena-data-client.js";
+import { selectedGraphQLOperation, athenaGraphQL } from "./athena-request.js";
+function useAthenaGraphQL(document, variables, options = {}) {
+  const config = useAthenaConfig();
+  const scope = useAthenaDataScope();
+  const client = useAthenaDataQueryClient();
+  const { operationName, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;
+  const text = String(document);
+  return useQuery(
+    {
+      retry: retryAthenaRead,
+      retryDelay: athenaRetryDelay,
+      staleTime: ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, AthenaDataKind.GraphQL, text, variables ?? {}, operationName ?? null],
+      queryFn: ({ signal }) => {
+        var _a;
+        if (((_a = selectedGraphQLOperation(text, operationName)) == null ? void 0 : _a.type) !== "query") {
+          throw new AthenaApiError({
+            kind: AthenaApiErrorKind.Request,
+            message: "useAthenaGraphQL runs one query: name it with operationName when the document holds several, and send a mutation with useAthenaGraphQLMutation",
+            method: "POST",
+            path: "/graphql"
+          });
+        }
+        return athenaGraphQL(config, text, variables, {
+          operationName,
+          timeoutMs,
+          rateLimitRetry,
+          headers,
+          signal
+        });
+      },
+      enabled: enabledAnd(enabled, config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+function useAthenaGraphQLMutation(document, options = {}) {
+  const config = useAthenaConfig();
+  const client = useAthenaDataQueryClient();
+  const { operationName, timeoutMs, rateLimitRetry, headers, ...mutationOptions } = options;
+  const text = String(document);
+  return useMutation(
+    {
+      ...mutationOptions,
+      // TODO(#54756): send an Idempotency-Key per call once agora honours one, so
+      // a write sent twice (a retry, a double click) applies once.
+      mutationFn: (variables) => athenaGraphQL(config, text, variables, {
+        operationName,
+        timeoutMs,
+        rateLimitRetry,
+        headers
+      })
+    },
+    client
+  );
+}
+export {
+  useAthenaGraphQL,
+  useAthenaGraphQLMutation
+};
+//# sourceMappingURL=use-athena-graphql.js.map

package/dist/data/use-athena-graphql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-graphql.js","sources":["../../src/data/use-athena-graphql.ts"],"sourcesContent":["/**\n * GraphQL on agora through TanStack Query, on the SDK's own client: a read\n * (`useAthenaGraphQL`) cached per identity and cancelled when its last reader\n * unmounts, and a write (`useAthenaGraphQLMutation`). Both run on the SDK's\n * transport (`athenaGraphQL`), so a read and a write carry the provider's\n * credential and fail as an `AthenaApiError`.\n */\nimport {\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n  useMutation,\n  useQuery,\n} from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport { AthenaApiError, AthenaApiErrorKind } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport {\n  type AthenaGraphQLDocument,\n  type AthenaGraphQLRequestOptions,\n  type AthenaGraphQLVariables,\n  athenaGraphQL,\n  selectedGraphQLOperation,\n} from './athena-request';\n\n/** Request options of a GraphQL hook (its `signal` is TanStack Query's). */\nexport type AthenaGraphQLHookRequestOptions = Omit<AthenaGraphQLRequestOptions, 'signal'>;\n\n/**\n * `useAthenaGraphQL`'s options: TanStack Query's (`enabled`, `select`,\n * `staleTime`, `refetchInterval`…) and the request's (`timeoutMs`,\n * `rateLimitRetry`, `operationName`, `headers`).\n */\nexport type UseAthenaGraphQLOptions<TData, TSelected = TData> = Omit<\n  UseQueryOptions<TData, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  AthenaGraphQLHookRequestOptions;\n\n/**\n * Read with one GraphQL query on agora's `/graphql`, as the signed-in person.\n * Keyed by the identity (see `useAthenaDataScope`), the document and its\n * variables. Never retried on a 4xx or a GraphQL error; a failure with no\n * answer or a 5xx is asked twice more. Cancelled when no component reads it\n * any more. A mutation is refused here (it would run again on every refetch):\n * send it with `useAthenaGraphQLMutation`.\n *\n * ```tsx\n * const { data, error } = useAthenaGraphQL<{ asset: { title: string } }, { id: string }>(\n *   `query Asset($id: String!) { asset(id: $id) { title } }`,\n *   { id },\n * );\n * ```\n */\nexport function useAthenaGraphQL<\n  TData = unknown,\n  TVariables extends object = AthenaGraphQLVariables,\n  TSelected = TData,\n>(\n  document: AthenaGraphQLDocument<TData, TVariables>,\n  variables?: TVariables,\n  options: UseAthenaGraphQLOptions<TData, TSelected> = {},\n): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  const { operationName, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;\n  const text = String(document);\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.GraphQL, text, variables ?? {}, operationName ?? null],\n      queryFn: ({ signal }) => {\n        // The operation agora would run (`operationName`'s, else the only\n        // one), never just the document's first: a mutation or subscription\n        // here would run again on every refetch.\n        if (selectedGraphQLOperation(text, operationName)?.type !== 'query') {\n          throw new AthenaApiError({\n            kind: AthenaApiErrorKind.Request,\n            message:\n              'useAthenaGraphQL runs one query: name it with operationName when the document holds several, and send a mutation with useAthenaGraphQLMutation',\n            method: 'POST',\n            path: '/graphql',\n          });\n        }\n        return athenaGraphQL<TData, TVariables>(config, text, variables, {\n          operationName,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n          signal,\n        });\n      },\n      enabled: enabledAnd(enabled, config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n\n/**\n * `useAthenaGraphQLMutation`'s options: TanStack Query's mutation options\n * (`onSuccess`, `onError`, `onMutate`…) and the request's.\n */\nexport type UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult = unknown> = Omit<\n  UseMutationOptions<TData, AthenaApiError, TVariables, TOnMutateResult>,\n  'mutationFn'\n> &\n  AthenaGraphQLHookRequestOptions;\n\n/**\n * Write with one GraphQL mutation on agora's `/graphql`, as the signed-in\n * person: `mutate(variables)` / `mutateAsync(variables)`. Never retried (a 429\n * from agora's limiter is waited out by the transport: it refuses before\n * anything runs). A write already sent is not cancelled when its component\n * unmounts, since agora may have applied it; `timeoutMs` still bounds it.\n * Read the reads it changes again with `useInvalidateAthenaQueries`.\n *\n * ```tsx\n * const invalidate = useInvalidateAthenaQueries();\n * const rename = useAthenaGraphQLMutation<RenameResult, { id: string; title: string }>(RENAME, {\n *   onSuccess: () => invalidate({ operationNames: ['Asset'] }),\n * });\n * rename.mutate({ id, title });\n * ```\n */\nexport function useAthenaGraphQLMutation<\n  TData = unknown,\n  TVariables extends object = AthenaGraphQLVariables,\n  TOnMutateResult = unknown,\n>(\n  document: AthenaGraphQLDocument<TData, TVariables>,\n  options: UseAthenaGraphQLMutationOptions<TData, TVariables, TOnMutateResult> = {},\n): UseMutationResult<TData, AthenaApiError, TVariables, TOnMutateResult> {\n  const config = useAthenaConfig();\n  const client = useAthenaDataQueryClient();\n  const { operationName, timeoutMs, rateLimitRetry, headers, ...mutationOptions } = options;\n  const text = String(document);\n  return useMutation(\n    {\n      ...mutationOptions,\n      // TODO(#54756): send an Idempotency-Key per call once agora honours one, so\n      // a write sent twice (a retry, a double click) applies once.\n      mutationFn: (variables: TVariables) =>\n        athenaGraphQL<TData, TVariables>(config, text, variables, {\n          operationName,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n        }),\n    },\n    client,\n  );\n}\n"],"names":[],"mappings":";;;;;AA+DO,SAAS,iBAKd,UACA,WACA,UAAqD,CAAA,GACV;AAC3C,QAAM,SAAS,gBAAA;AACf,QAAM,QAAQ,mBAAA;AACd,QAAM,SAAS,yBAAA;AACf,QAAM,EAAE,eAAe,WAAW,gBAAgB,SAAS,SAAS,GAAG,iBAAiB;AACxF,QAAM,OAAO,OAAO,QAAQ;AAC5B,SAAO;AAAA,IACL;AAAA,MACE,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,WAAW;AAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAO,eAAe,SAAS,MAAM,aAAa,CAAA,GAAI,iBAAiB,IAAI;AAAA,MACzF,SAAS,CAAC,EAAE,aAAa;;AAIvB,cAAI,8BAAyB,MAAM,aAAa,MAA5C,mBAA+C,UAAS,SAAS;AACnE,gBAAM,IAAI,eAAe;AAAA,YACvB,MAAM,mBAAmB;AAAA,YACzB,SACE;AAAA,YACF,QAAQ;AAAA,YACR,MAAM;AAAA,UAAA,CACP;AAAA,QACH;AACA,eAAO,cAAiC,QAAQ,MAAM,WAAW;AAAA,UAC/D;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QAAA,CACD;AAAA,MACH;AAAA,MACA,SAAS,WAAW,SAAS,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAE3D;AAAA,EAAA;AAEJ;AA4BO,SAAS,yBAKd,UACA,UAA+E,IACR;AACvE,QAAM,SAAS,gBAAA;AACf,QAAM,SAAS,yBAAA;AACf,QAAM,EAAE,eAAe,WAAW,gBAAgB,SAAS,GAAG,oBAAoB;AAClF,QAAM,OAAO,OAAO,QAAQ;AAC5B,SAAO;AAAA,IACL;AAAA,MACE,GAAG;AAAA;AAAA;AAAA,MAGH,YAAY,CAAC,cACX,cAAiC,QAAQ,MAAM,WAAW;AAAA,QACxD;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,IAAA;AAAA,IAEL;AAAA,EAAA;AAEJ;"}

package/dist/data/use-athena-rest.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const reactQuery = require("@tanstack/react-query");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const athenaDataClient = require("./athena-data-client.cjs");
+const athenaRequest = require("./athena-request.cjs");
+function useAthenaRest(path, options = {}) {
+  const config = AthenaContext.useAthenaConfig();
+  const scope = athenaDataClient.useAthenaDataScope();
+  const client = athenaDataClient.useAthenaDataQueryClient();
+  const { params, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;
+  return reactQuery.useQuery(
+    {
+      retry: athenaDataClient.retryAthenaRead,
+      retryDelay: athenaDataClient.athenaRetryDelay,
+      staleTime: athenaDataClient.ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, athenaDataClient.AthenaDataKind.Rest, path, params ?? {}],
+      queryFn: ({ signal }) => athenaRequest.athenaFetchJson(config, path ?? "", {
+        method: "GET",
+        params,
+        timeoutMs,
+        rateLimitRetry,
+        headers,
+        signal
+      }),
+      enabled: athenaDataClient.enabledAnd(enabled, path !== null && config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+exports.useAthenaRest = useAthenaRest;
+//# sourceMappingURL=use-athena-rest.cjs.map

package/dist/data/use-athena-rest.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-rest.cjs","sources":["../../src/data/use-athena-rest.ts"],"sourcesContent":["import { type UseQueryOptions, type UseQueryResult, useQuery } from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport type { AthenaApiError } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport { type AthenaRequestOptions, athenaFetchJson } from './athena-request';\n\n/**\n * `useAthenaRest`'s options: TanStack Query's (`enabled`, `select`,\n * `staleTime`…), the query-string `params` (part of the cache key) and the\n * request's (`timeoutMs`, `rateLimitRetry`, `headers`).\n */\nexport type UseAthenaRestOptions<TData, TSelected = TData> = Omit<\n  UseQueryOptions<TData, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  Pick<AthenaRequestOptions, 'params' | 'timeoutMs' | 'rateLimitRetry' | 'headers'>;\n\n/**\n * Read one of agora's JSON `GET` routes as the signed-in person: `path` under\n * the provider's `backendUrl` (`/api/v0/me`, `/api/v0/assets/{id}`…), `null`\n * to hold the read idle. Cached per identity, path and `params`; retried and\n * cancelled as `useAthenaGraphQL` is. `TData` is the caller's word for what the\n * route answers.\n *\n * ```tsx\n * const me = useAthenaRest<{ user_id: string; workspace_id: string }>('/api/v0/me');\n * ```\n */\nexport function useAthenaRest<TData = unknown, TSelected = TData>(\n  path: string | null,\n  options: UseAthenaRestOptions<TData, TSelected> = {},\n): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  const { params, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.Rest, path, params ?? {}],\n      queryFn: ({ signal }) =>\n        athenaFetchJson<TData>(config, path ?? '', {\n          method: 'GET',\n          params,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n          signal,\n        }),\n      enabled: enabledAnd(enabled, path !== null && config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n"],"names":["useAthenaConfig","useAthenaDataScope","useAthenaDataQueryClient","useQuery","retryAthenaRead","athenaRetryDelay","ATHENA_DATA_STALE_MS","AthenaDataKind","athenaFetchJson","enabledAnd"],"mappings":";;;;;;AAoCO,SAAS,cACd,MACA,UAAkD,IACP;AAC3C,QAAM,SAASA,cAAAA,gBAAA;AACf,QAAM,QAAQC,iBAAAA,mBAAA;AACd,QAAM,SAASC,iBAAAA,yBAAA;AACf,QAAM,EAAE,QAAQ,WAAW,gBAAgB,SAAS,SAAS,GAAG,iBAAiB;AACjF,SAAOC,WAAAA;AAAAA,IACL;AAAA,MACE,OAAOC,iBAAAA;AAAAA,MACP,YAAYC,iBAAAA;AAAAA,MACZ,WAAWC,iBAAAA;AAAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAOC,iBAAAA,eAAe,MAAM,MAAM,UAAU,EAAE;AAAA,MAC5D,SAAS,CAAC,EAAE,OAAA,MACVC,cAAAA,gBAAuB,QAAQ,QAAQ,IAAI;AAAA,QACzC,QAAQ;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,MACH,SAASC,iBAAAA,WAAW,SAAS,SAAS,QAAQ,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAE5E;AAAA,EAAA;AAEJ;;"}

package/dist/data/use-athena-rest.d.ts

@@ -0,0 +1,21 @@
+import { type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import type { AthenaApiError } from './athena-api-error';
+import { type AthenaRequestOptions } from './athena-request';
+/**
+ * `useAthenaRest`'s options: TanStack Query's (`enabled`, `select`,
+ * `staleTime`…), the query-string `params` (part of the cache key) and the
+ * request's (`timeoutMs`, `rateLimitRetry`, `headers`).
+ */
+export type UseAthenaRestOptions<TData, TSelected = TData> = Omit<UseQueryOptions<TData, AthenaApiError, TSelected>, 'queryKey' | 'queryFn'> & Pick<AthenaRequestOptions, 'params' | 'timeoutMs' | 'rateLimitRetry' | 'headers'>;
+/**
+ * Read one of agora's JSON `GET` routes as the signed-in person: `path` under
+ * the provider's `backendUrl` (`/api/v0/me`, `/api/v0/assets/{id}`…), `null`
+ * to hold the read idle. Cached per identity, path and `params`; retried and
+ * cancelled as `useAthenaGraphQL` is. `TData` is the caller's word for what the
+ * route answers.
+ *
+ * ```tsx
+ * const me = useAthenaRest<{ user_id: string; workspace_id: string }>('/api/v0/me');
+ * ```
+ */
+export declare function useAthenaRest<TData = unknown, TSelected = TData>(path: string | null, options?: UseAthenaRestOptions<TData, TSelected>): UseQueryResult<TSelected, AthenaApiError>;

package/dist/data/use-athena-rest.js

@@ -0,0 +1,33 @@
+import { useQuery } from "@tanstack/react-query";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { useAthenaDataScope, useAthenaDataQueryClient, AthenaDataKind, ATHENA_DATA_STALE_MS, athenaRetryDelay, retryAthenaRead, enabledAnd } from "./athena-data-client.js";
+import { athenaFetchJson } from "./athena-request.js";
+function useAthenaRest(path, options = {}) {
+  const config = useAthenaConfig();
+  const scope = useAthenaDataScope();
+  const client = useAthenaDataQueryClient();
+  const { params, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;
+  return useQuery(
+    {
+      retry: retryAthenaRead,
+      retryDelay: athenaRetryDelay,
+      staleTime: ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, AthenaDataKind.Rest, path, params ?? {}],
+      queryFn: ({ signal }) => athenaFetchJson(config, path ?? "", {
+        method: "GET",
+        params,
+        timeoutMs,
+        rateLimitRetry,
+        headers,
+        signal
+      }),
+      enabled: enabledAnd(enabled, path !== null && config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+export {
+  useAthenaRest
+};
+//# sourceMappingURL=use-athena-rest.js.map

package/dist/data/use-athena-rest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-athena-rest.js","sources":["../../src/data/use-athena-rest.ts"],"sourcesContent":["import { type UseQueryOptions, type UseQueryResult, useQuery } from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport type { AthenaApiError } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport { type AthenaRequestOptions, athenaFetchJson } from './athena-request';\n\n/**\n * `useAthenaRest`'s options: TanStack Query's (`enabled`, `select`,\n * `staleTime`…), the query-string `params` (part of the cache key) and the\n * request's (`timeoutMs`, `rateLimitRetry`, `headers`).\n */\nexport type UseAthenaRestOptions<TData, TSelected = TData> = Omit<\n  UseQueryOptions<TData, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  Pick<AthenaRequestOptions, 'params' | 'timeoutMs' | 'rateLimitRetry' | 'headers'>;\n\n/**\n * Read one of agora's JSON `GET` routes as the signed-in person: `path` under\n * the provider's `backendUrl` (`/api/v0/me`, `/api/v0/assets/{id}`…), `null`\n * to hold the read idle. Cached per identity, path and `params`; retried and\n * cancelled as `useAthenaGraphQL` is. `TData` is the caller's word for what the\n * route answers.\n *\n * ```tsx\n * const me = useAthenaRest<{ user_id: string; workspace_id: string }>('/api/v0/me');\n * ```\n */\nexport function useAthenaRest<TData = unknown, TSelected = TData>(\n  path: string | null,\n  options: UseAthenaRestOptions<TData, TSelected> = {},\n): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  const { params, timeoutMs, rateLimitRetry, headers, enabled, ...queryOptions } = options;\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.Rest, path, params ?? {}],\n      queryFn: ({ signal }) =>\n        athenaFetchJson<TData>(config, path ?? '', {\n          method: 'GET',\n          params,\n          timeoutMs,\n          rateLimitRetry,\n          headers,\n          signal,\n        }),\n      enabled: enabledAnd(enabled, path !== null && config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n"],"names":[],"mappings":";;;;AAoCO,SAAS,cACd,MACA,UAAkD,IACP;AAC3C,QAAM,SAAS,gBAAA;AACf,QAAM,QAAQ,mBAAA;AACd,QAAM,SAAS,yBAAA;AACf,QAAM,EAAE,QAAQ,WAAW,gBAAgB,SAAS,SAAS,GAAG,iBAAiB;AACjF,SAAO;AAAA,IACL;AAAA,MACE,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,WAAW;AAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAO,eAAe,MAAM,MAAM,UAAU,EAAE;AAAA,MAC5D,SAAS,CAAC,EAAE,OAAA,MACV,gBAAuB,QAAQ,QAAQ,IAAI;AAAA,QACzC,QAAQ;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,MACH,SAAS,WAAW,SAAS,SAAS,QAAQ,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAE5E;AAAA,EAAA;AAEJ;"}

package/dist/data/use-semantic-query.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const reactQuery = require("@tanstack/react-query");
+const AthenaContext = require("../provider/AthenaContext.cjs");
+const athenaDataClient = require("./athena-data-client.cjs");
+const athenaRequest = require("./athena-request.cjs");
+function semanticQueryPath(semanticModelId) {
+  return `/api/v0/semantic-model/${encodeURIComponent(semanticModelId)}/query`;
+}
+const SEMANTIC_QUERY_TIMEOUT_MS = 9e4;
+function useSemanticQuery({
+  semanticModelId,
+  query,
+  timeoutMs = SEMANTIC_QUERY_TIMEOUT_MS,
+  rateLimitRetry,
+  enabled,
+  ...queryOptions
+}) {
+  const config = AthenaContext.useAthenaConfig();
+  const scope = athenaDataClient.useAthenaDataScope();
+  const client = athenaDataClient.useAthenaDataQueryClient();
+  return reactQuery.useQuery(
+    {
+      retry: athenaDataClient.retryAthenaRead,
+      retryDelay: athenaDataClient.athenaRetryDelay,
+      staleTime: athenaDataClient.ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, athenaDataClient.AthenaDataKind.SemanticQuery, semanticModelId, query],
+      queryFn: ({ signal }) => athenaRequest.athenaFetchJson(config, semanticQueryPath(semanticModelId ?? ""), {
+        method: "POST",
+        json: query,
+        timeoutMs,
+        rateLimitRetry,
+        signal
+      }),
+      enabled: athenaDataClient.enabledAnd(enabled, semanticModelId !== null && config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+exports.SEMANTIC_QUERY_TIMEOUT_MS = SEMANTIC_QUERY_TIMEOUT_MS;
+exports.semanticQueryPath = semanticQueryPath;
+exports.useSemanticQuery = useSemanticQuery;
+//# sourceMappingURL=use-semantic-query.cjs.map

package/dist/data/use-semantic-query.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-semantic-query.cjs","sources":["../../src/data/use-semantic-query.ts"],"sourcesContent":["/**\n * A semantic model's metrics, read through agora's public semantic query API\n * (`POST /api/v0/semantic-model/{asset_id}/query`, `query_semantic_model` in\n * `agora/agora/web/api/public/v0/views/semantic_model.py`). The query runs as\n * the signed-in person: agora checks their access to the model, and to its\n * lakehouse sources, before Cube runs it. The types below are that route's own\n * request and response (`SemanticModelQueryRequestIn`,\n * `SemanticModelQueryResponseOut` in `agora/openapi.json`), field for field.\n */\nimport { type UseQueryOptions, type UseQueryResult, useQuery } from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport type { AthenaApiError } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport { type AthenaRequestOptions, athenaFetchJson } from './athena-request';\n\n/** An order entry: `[member, direction]`, or `{ member, direction }`. */\nexport type AthenaSemanticOrder =\n  | readonly [member: string, direction: 'asc' | 'desc']\n  | { member: string; direction?: 'asc' | 'desc' };\n\n/** A metric query (`SemanticModelQueryRequestIn`). */\nexport interface AthenaSemanticQuery {\n  /** Measure identifiers, e.g. `[\"orders.total_revenue\"]`. */\n  measures: readonly string[];\n  /** Dimension identifiers to group by. */\n  dimensions?: readonly string[];\n  /** Cube filters. */\n  filters?: readonly Readonly<Record<string, unknown>>[];\n  /**\n   * Cube time dimensions, e.g.\n   * `[{ dimension: 'orders.created_at', granularity: 'month', dateRange: ['2026-01-01', '2026-06-30'] }]`.\n   */\n  time_dimensions?: readonly Readonly<Record<string, unknown>>[];\n  /** The order applied before `limit` (a server-side top N). */\n  order?: readonly AthenaSemanticOrder[];\n  /** At most this many rows, 1 to 5000 (agora's default 100); `truncated` says when there were more. */\n  limit?: number;\n}\n\n/** One source table's Iceberg state when the query ran (`SemanticModelSourceSnapshotOut`). */\nexport interface AthenaSemanticSourceSnapshot {\n  namespace: string;\n  table: string;\n  table_uuid: string;\n  snapshot_id?: string | null;\n  committed_at?: string | null;\n}\n\n/**\n * A metric query's answer (`SemanticModelQueryResponseOut`). The fields after\n * `row_count` are optional: an older agora leaves them out.\n */\nexport interface AthenaSemanticQueryResult {\n  /** The rows, keyed by member. */\n  data: Record<string, unknown>[];\n  row_count: number;\n  /** True when the query had more rows than `limit`. */\n  truncated?: boolean;\n  /** How long the semantic layer and its engine took, in ms. */\n  elapsed_ms?: number;\n  /** When the data is current as of (ISO-8601 UTC); `null` when the engine exposes no snapshot. */\n  data_as_of?: string | null;\n  /** `'snapshot'` (lakehouse snapshots) or `'query_time'`. */\n  as_of_kind?: string | null;\n  /** When the engine computed the result (ISO-8601 UTC). */\n  queried_at?: string | null;\n  source_snapshots?: AthenaSemanticSourceSnapshot[] | null;\n  /** The deployed model definition that computed the rows. */\n  schema_hash?: string | null;\n  schema_version?: number | null;\n}\n\n/** The public semantic query route of a model. */\nexport function semanticQueryPath(semanticModelId: string): string {\n  return `/api/v0/semantic-model/${encodeURIComponent(semanticModelId)}/query`;\n}\n\n/**\n * agora waits up to 60 s for the semantic layer before it answers 504 with\n * `Retry-After: 15`, so a semantic query is given longer than other requests.\n */\nexport const SEMANTIC_QUERY_TIMEOUT_MS = 90_000;\n\nexport type UseSemanticQueryOptions<TSelected = AthenaSemanticQueryResult> = Omit<\n  UseQueryOptions<AthenaSemanticQueryResult, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  Pick<AthenaRequestOptions, 'timeoutMs' | 'rateLimitRetry'> & {\n    /** The semantic model asset (`asset_…`); `null` holds the read idle. */\n    semanticModelId: string | null;\n    query: AthenaSemanticQuery;\n  };\n\n/**\n * Run a metric query on a semantic model as the signed-in person. Cached per\n * identity, model and query; a 504 (the engine still computing) is asked again\n * after the `Retry-After` agora sends, which joins the query still running;\n * a refusal (401 / 403 / 404) or an invalid query (400 / 422) is not.\n *\n * ```tsx\n * const revenue = useSemanticQuery({\n *   semanticModelId,\n *   query: { measures: ['orders.total_revenue'], dimensions: ['orders.region'], limit: 20 },\n * });\n * ```\n */\nexport function useSemanticQuery<TSelected = AthenaSemanticQueryResult>({\n  semanticModelId,\n  query,\n  timeoutMs = SEMANTIC_QUERY_TIMEOUT_MS,\n  rateLimitRetry,\n  enabled,\n  ...queryOptions\n}: UseSemanticQueryOptions<TSelected>): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.SemanticQuery, semanticModelId, query],\n      queryFn: ({ signal }) =>\n        athenaFetchJson<AthenaSemanticQueryResult>(config, semanticQueryPath(semanticModelId ?? ''), {\n          method: 'POST',\n          json: query,\n          timeoutMs,\n          rateLimitRetry,\n          signal,\n        }),\n      enabled: enabledAnd(enabled, semanticModelId !== null && config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n"],"names":["useAthenaConfig","useAthenaDataScope","useAthenaDataQueryClient","useQuery","retryAthenaRead","athenaRetryDelay","ATHENA_DATA_STALE_MS","AthenaDataKind","athenaFetchJson","enabledAnd"],"mappings":";;;;;;AAiFO,SAAS,kBAAkB,iBAAiC;AACjE,SAAO,0BAA0B,mBAAmB,eAAe,CAAC;AACtE;AAMO,MAAM,4BAA4B;AAyBlC,SAAS,iBAAwD;AAAA,EACtE;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAkF;AAChF,QAAM,SAASA,cAAAA,gBAAA;AACf,QAAM,QAAQC,iBAAAA,mBAAA;AACd,QAAM,SAASC,iBAAAA,yBAAA;AACf,SAAOC,WAAAA;AAAAA,IACL;AAAA,MACE,OAAOC,iBAAAA;AAAAA,MACP,YAAYC,iBAAAA;AAAAA,MACZ,WAAWC,iBAAAA;AAAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAOC,iBAAAA,eAAe,eAAe,iBAAiB,KAAK;AAAA,MACzE,SAAS,CAAC,EAAE,aACVC,cAAAA,gBAA2C,QAAQ,kBAAkB,mBAAmB,EAAE,GAAG;AAAA,QAC3F,QAAQ;AAAA,QACR,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,MACH,SAASC,iBAAAA,WAAW,SAAS,oBAAoB,QAAQ,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAEvF;AAAA,EAAA;AAEJ;;;;"}

package/dist/data/use-semantic-query.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A semantic model's metrics, read through agora's public semantic query API
+ * (`POST /api/v0/semantic-model/{asset_id}/query`, `query_semantic_model` in
+ * `agora/agora/web/api/public/v0/views/semantic_model.py`). The query runs as
+ * the signed-in person: agora checks their access to the model, and to its
+ * lakehouse sources, before Cube runs it. The types below are that route's own
+ * request and response (`SemanticModelQueryRequestIn`,
+ * `SemanticModelQueryResponseOut` in `agora/openapi.json`), field for field.
+ */
+import { type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+import type { AthenaApiError } from './athena-api-error';
+import { type AthenaRequestOptions } from './athena-request';
+/** An order entry: `[member, direction]`, or `{ member, direction }`. */
+export type AthenaSemanticOrder = readonly [member: string, direction: 'asc' | 'desc'] | {
+    member: string;
+    direction?: 'asc' | 'desc';
+};
+/** A metric query (`SemanticModelQueryRequestIn`). */
+export interface AthenaSemanticQuery {
+    /** Measure identifiers, e.g. `["orders.total_revenue"]`. */
+    measures: readonly string[];
+    /** Dimension identifiers to group by. */
+    dimensions?: readonly string[];
+    /** Cube filters. */
+    filters?: readonly Readonly<Record<string, unknown>>[];
+    /**
+     * Cube time dimensions, e.g.
+     * `[{ dimension: 'orders.created_at', granularity: 'month', dateRange: ['2026-01-01', '2026-06-30'] }]`.
+     */
+    time_dimensions?: readonly Readonly<Record<string, unknown>>[];
+    /** The order applied before `limit` (a server-side top N). */
+    order?: readonly AthenaSemanticOrder[];
+    /** At most this many rows, 1 to 5000 (agora's default 100); `truncated` says when there were more. */
+    limit?: number;
+}
+/** One source table's Iceberg state when the query ran (`SemanticModelSourceSnapshotOut`). */
+export interface AthenaSemanticSourceSnapshot {
+    namespace: string;
+    table: string;
+    table_uuid: string;
+    snapshot_id?: string | null;
+    committed_at?: string | null;
+}
+/**
+ * A metric query's answer (`SemanticModelQueryResponseOut`). The fields after
+ * `row_count` are optional: an older agora leaves them out.
+ */
+export interface AthenaSemanticQueryResult {
+    /** The rows, keyed by member. */
+    data: Record<string, unknown>[];
+    row_count: number;
+    /** True when the query had more rows than `limit`. */
+    truncated?: boolean;
+    /** How long the semantic layer and its engine took, in ms. */
+    elapsed_ms?: number;
+    /** When the data is current as of (ISO-8601 UTC); `null` when the engine exposes no snapshot. */
+    data_as_of?: string | null;
+    /** `'snapshot'` (lakehouse snapshots) or `'query_time'`. */
+    as_of_kind?: string | null;
+    /** When the engine computed the result (ISO-8601 UTC). */
+    queried_at?: string | null;
+    source_snapshots?: AthenaSemanticSourceSnapshot[] | null;
+    /** The deployed model definition that computed the rows. */
+    schema_hash?: string | null;
+    schema_version?: number | null;
+}
+/** The public semantic query route of a model. */
+export declare function semanticQueryPath(semanticModelId: string): string;
+/**
+ * agora waits up to 60 s for the semantic layer before it answers 504 with
+ * `Retry-After: 15`, so a semantic query is given longer than other requests.
+ */
+export declare const SEMANTIC_QUERY_TIMEOUT_MS = 90000;
+export type UseSemanticQueryOptions<TSelected = AthenaSemanticQueryResult> = Omit<UseQueryOptions<AthenaSemanticQueryResult, AthenaApiError, TSelected>, 'queryKey' | 'queryFn'> & Pick<AthenaRequestOptions, 'timeoutMs' | 'rateLimitRetry'> & {
+    /** The semantic model asset (`asset_…`); `null` holds the read idle. */
+    semanticModelId: string | null;
+    query: AthenaSemanticQuery;
+};
+/**
+ * Run a metric query on a semantic model as the signed-in person. Cached per
+ * identity, model and query; a 504 (the engine still computing) is asked again
+ * after the `Retry-After` agora sends, which joins the query still running;
+ * a refusal (401 / 403 / 404) or an invalid query (400 / 422) is not.
+ *
+ * ```tsx
+ * const revenue = useSemanticQuery({
+ *   semanticModelId,
+ *   query: { measures: ['orders.total_revenue'], dimensions: ['orders.region'], limit: 20 },
+ * });
+ * ```
+ */
+export declare function useSemanticQuery<TSelected = AthenaSemanticQueryResult>({ semanticModelId, query, timeoutMs, rateLimitRetry, enabled, ...queryOptions }: UseSemanticQueryOptions<TSelected>): UseQueryResult<TSelected, AthenaApiError>;

package/dist/data/use-semantic-query.js

@@ -0,0 +1,44 @@
+import { useQuery } from "@tanstack/react-query";
+import { useAthenaConfig } from "../provider/AthenaContext.js";
+import { useAthenaDataScope, useAthenaDataQueryClient, AthenaDataKind, ATHENA_DATA_STALE_MS, athenaRetryDelay, retryAthenaRead, enabledAnd } from "./athena-data-client.js";
+import { athenaFetchJson } from "./athena-request.js";
+function semanticQueryPath(semanticModelId) {
+  return `/api/v0/semantic-model/${encodeURIComponent(semanticModelId)}/query`;
+}
+const SEMANTIC_QUERY_TIMEOUT_MS = 9e4;
+function useSemanticQuery({
+  semanticModelId,
+  query,
+  timeoutMs = SEMANTIC_QUERY_TIMEOUT_MS,
+  rateLimitRetry,
+  enabled,
+  ...queryOptions
+}) {
+  const config = useAthenaConfig();
+  const scope = useAthenaDataScope();
+  const client = useAthenaDataQueryClient();
+  return useQuery(
+    {
+      retry: retryAthenaRead,
+      retryDelay: athenaRetryDelay,
+      staleTime: ATHENA_DATA_STALE_MS,
+      ...queryOptions,
+      queryKey: [...scope, AthenaDataKind.SemanticQuery, semanticModelId, query],
+      queryFn: ({ signal }) => athenaFetchJson(config, semanticQueryPath(semanticModelId ?? ""), {
+        method: "POST",
+        json: query,
+        timeoutMs,
+        rateLimitRetry,
+        signal
+      }),
+      enabled: enabledAnd(enabled, semanticModelId !== null && config.backendUrl.length > 0)
+    },
+    client
+  );
+}
+export {
+  SEMANTIC_QUERY_TIMEOUT_MS,
+  semanticQueryPath,
+  useSemanticQuery
+};
+//# sourceMappingURL=use-semantic-query.js.map

package/dist/data/use-semantic-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-semantic-query.js","sources":["../../src/data/use-semantic-query.ts"],"sourcesContent":["/**\n * A semantic model's metrics, read through agora's public semantic query API\n * (`POST /api/v0/semantic-model/{asset_id}/query`, `query_semantic_model` in\n * `agora/agora/web/api/public/v0/views/semantic_model.py`). The query runs as\n * the signed-in person: agora checks their access to the model, and to its\n * lakehouse sources, before Cube runs it. The types below are that route's own\n * request and response (`SemanticModelQueryRequestIn`,\n * `SemanticModelQueryResponseOut` in `agora/openapi.json`), field for field.\n */\nimport { type UseQueryOptions, type UseQueryResult, useQuery } from '@tanstack/react-query';\nimport { useAthenaConfig } from '../provider/AthenaContext';\nimport type { AthenaApiError } from './athena-api-error';\nimport {\n  ATHENA_DATA_STALE_MS,\n  AthenaDataKind,\n  athenaRetryDelay,\n  enabledAnd,\n  retryAthenaRead,\n  useAthenaDataQueryClient,\n  useAthenaDataScope,\n} from './athena-data-client';\nimport { type AthenaRequestOptions, athenaFetchJson } from './athena-request';\n\n/** An order entry: `[member, direction]`, or `{ member, direction }`. */\nexport type AthenaSemanticOrder =\n  | readonly [member: string, direction: 'asc' | 'desc']\n  | { member: string; direction?: 'asc' | 'desc' };\n\n/** A metric query (`SemanticModelQueryRequestIn`). */\nexport interface AthenaSemanticQuery {\n  /** Measure identifiers, e.g. `[\"orders.total_revenue\"]`. */\n  measures: readonly string[];\n  /** Dimension identifiers to group by. */\n  dimensions?: readonly string[];\n  /** Cube filters. */\n  filters?: readonly Readonly<Record<string, unknown>>[];\n  /**\n   * Cube time dimensions, e.g.\n   * `[{ dimension: 'orders.created_at', granularity: 'month', dateRange: ['2026-01-01', '2026-06-30'] }]`.\n   */\n  time_dimensions?: readonly Readonly<Record<string, unknown>>[];\n  /** The order applied before `limit` (a server-side top N). */\n  order?: readonly AthenaSemanticOrder[];\n  /** At most this many rows, 1 to 5000 (agora's default 100); `truncated` says when there were more. */\n  limit?: number;\n}\n\n/** One source table's Iceberg state when the query ran (`SemanticModelSourceSnapshotOut`). */\nexport interface AthenaSemanticSourceSnapshot {\n  namespace: string;\n  table: string;\n  table_uuid: string;\n  snapshot_id?: string | null;\n  committed_at?: string | null;\n}\n\n/**\n * A metric query's answer (`SemanticModelQueryResponseOut`). The fields after\n * `row_count` are optional: an older agora leaves them out.\n */\nexport interface AthenaSemanticQueryResult {\n  /** The rows, keyed by member. */\n  data: Record<string, unknown>[];\n  row_count: number;\n  /** True when the query had more rows than `limit`. */\n  truncated?: boolean;\n  /** How long the semantic layer and its engine took, in ms. */\n  elapsed_ms?: number;\n  /** When the data is current as of (ISO-8601 UTC); `null` when the engine exposes no snapshot. */\n  data_as_of?: string | null;\n  /** `'snapshot'` (lakehouse snapshots) or `'query_time'`. */\n  as_of_kind?: string | null;\n  /** When the engine computed the result (ISO-8601 UTC). */\n  queried_at?: string | null;\n  source_snapshots?: AthenaSemanticSourceSnapshot[] | null;\n  /** The deployed model definition that computed the rows. */\n  schema_hash?: string | null;\n  schema_version?: number | null;\n}\n\n/** The public semantic query route of a model. */\nexport function semanticQueryPath(semanticModelId: string): string {\n  return `/api/v0/semantic-model/${encodeURIComponent(semanticModelId)}/query`;\n}\n\n/**\n * agora waits up to 60 s for the semantic layer before it answers 504 with\n * `Retry-After: 15`, so a semantic query is given longer than other requests.\n */\nexport const SEMANTIC_QUERY_TIMEOUT_MS = 90_000;\n\nexport type UseSemanticQueryOptions<TSelected = AthenaSemanticQueryResult> = Omit<\n  UseQueryOptions<AthenaSemanticQueryResult, AthenaApiError, TSelected>,\n  'queryKey' | 'queryFn'\n> &\n  Pick<AthenaRequestOptions, 'timeoutMs' | 'rateLimitRetry'> & {\n    /** The semantic model asset (`asset_…`); `null` holds the read idle. */\n    semanticModelId: string | null;\n    query: AthenaSemanticQuery;\n  };\n\n/**\n * Run a metric query on a semantic model as the signed-in person. Cached per\n * identity, model and query; a 504 (the engine still computing) is asked again\n * after the `Retry-After` agora sends, which joins the query still running;\n * a refusal (401 / 403 / 404) or an invalid query (400 / 422) is not.\n *\n * ```tsx\n * const revenue = useSemanticQuery({\n *   semanticModelId,\n *   query: { measures: ['orders.total_revenue'], dimensions: ['orders.region'], limit: 20 },\n * });\n * ```\n */\nexport function useSemanticQuery<TSelected = AthenaSemanticQueryResult>({\n  semanticModelId,\n  query,\n  timeoutMs = SEMANTIC_QUERY_TIMEOUT_MS,\n  rateLimitRetry,\n  enabled,\n  ...queryOptions\n}: UseSemanticQueryOptions<TSelected>): UseQueryResult<TSelected, AthenaApiError> {\n  const config = useAthenaConfig();\n  const scope = useAthenaDataScope();\n  const client = useAthenaDataQueryClient();\n  return useQuery(\n    {\n      retry: retryAthenaRead,\n      retryDelay: athenaRetryDelay,\n      staleTime: ATHENA_DATA_STALE_MS,\n      ...queryOptions,\n      queryKey: [...scope, AthenaDataKind.SemanticQuery, semanticModelId, query],\n      queryFn: ({ signal }) =>\n        athenaFetchJson<AthenaSemanticQueryResult>(config, semanticQueryPath(semanticModelId ?? ''), {\n          method: 'POST',\n          json: query,\n          timeoutMs,\n          rateLimitRetry,\n          signal,\n        }),\n      enabled: enabledAnd(enabled, semanticModelId !== null && config.backendUrl.length > 0),\n    },\n    client,\n  );\n}\n"],"names":[],"mappings":";;;;AAiFO,SAAS,kBAAkB,iBAAiC;AACjE,SAAO,0BAA0B,mBAAmB,eAAe,CAAC;AACtE;AAMO,MAAM,4BAA4B;AAyBlC,SAAS,iBAAwD;AAAA,EACtE;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAkF;AAChF,QAAM,SAAS,gBAAA;AACf,QAAM,QAAQ,mBAAA;AACd,QAAM,SAAS,yBAAA;AACf,SAAO;AAAA,IACL;AAAA,MACE,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,WAAW;AAAA,MACX,GAAG;AAAA,MACH,UAAU,CAAC,GAAG,OAAO,eAAe,eAAe,iBAAiB,KAAK;AAAA,MACzE,SAAS,CAAC,EAAE,aACV,gBAA2C,QAAQ,kBAAkB,mBAAmB,EAAE,GAAG;AAAA,QAC3F,QAAQ;AAAA,QACR,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA;AAAA,MAAA,CACD;AAAA,MACH,SAAS,WAAW,SAAS,oBAAoB,QAAQ,OAAO,WAAW,SAAS,CAAC;AAAA,IAAA;AAAA,IAEvF;AAAA,EAAA;AAEJ;"}