@hypequery/react 0.1.1 → 0.2.0

package/README.md

@@ -1,377 +1,306 @@
 # @hypequery/react
 
-Type-safe React hooks for hypequery APIs. Wraps your generated API definition in thin TanStack Query shims so you can call `useQuery('weeklyRevenue')` with end-to-end type safety.
+React hooks for typed Hypequery HTTP endpoints, built on TanStack Query.
 
-## Installation
+Use `@hypequery/react` with APIs created by `@hypequery/serve`. The hooks call generated routes and infer input/output types from the API type you pass in.
+
+## Install
 
 ```bash
 npm install @hypequery/react @tanstack/react-query
+# or
+pnpm add @hypequery/react @tanstack/react-query
 ```
 
-Peer dependencies: `react@^18`, `@tanstack/react-query@^5`.
-
 ## Quick Start
 
-```ts
-// lib/analytics.ts
-import { createHooks } from '@hypequery/react';
-import type { Api } from '@/analytics/queries';
+Given a serve API:
 
-export const { useQuery, useMutation } = createHooks<Api>({
-  baseUrl: '/api',
+```ts
+// server/api.ts
+import { initServe } from '@hypequery/serve';
+import { z } from 'zod';
+import { db } from './db.js';
+
+const { query, serve } = initServe({
+  context: () => ({ db }),
+  basePath: '/api/analytics',
 });
-```
 
-Wrap your app with TanStack Query's provider:
+const weeklyRevenue = query({
+  description: 'Weekly revenue',
+  input: z.object({ startDate: z.string() }),
+  query: ({ ctx, input }) =>
+    ctx.db
+      .table('orders')
+      .where('created_at', 'gte', input.startDate)
+      .sum('total', 'revenue')
+      .execute(),
+});
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+export const api = serve({
+  queries: { weeklyRevenue },
+});
 
-const queryClient = new QueryClient();
+api.route('/weeklyRevenue', api.queries.weeklyRevenue);
 
-export function App({ children }: { children: React.ReactNode }) {
-  return (
-    <QueryClientProvider client={queryClient}>
-      {children}
-    </QueryClientProvider>
-  );
-}
+export type AnalyticsApi = typeof api;
 ```
 
-Use the hooks in your components:
+Create hooks on the client:
 
 ```tsx
-// Query
-const { data, error, isLoading } = useQuery('weeklyRevenue', { startDate: '2025-01-01' });
-
-// Mutation
-const rebuild = useMutation('rebuildMetrics');
-rebuild.mutate({ force: true });
-```
-
----
-
-## API Reference
-
-### `createHooks<Api>(config)`
-
-Factory function that creates type-safe `useQuery` and `useMutation` hooks for your API.
-
-**Parameters:**
-
-```ts
-interface CreateHooksConfig<TApi> {
-  baseUrl: string;                          // Required: API base URL (e.g., '/api' or 'https://api.example.com')
-  fetchFn?: typeof fetch;                   // Optional: Custom fetch implementation (defaults to global fetch)
-  headers?: Record<string, string | undefined> | (() => Record<string, string | undefined>); // Optional: Default headers or a resolver function
-  config?: Record<string, QueryMethodConfig>; // Optional: Per-route HTTP method overrides
-  api?: TApi;                               // Optional: API object to auto-extract HTTP methods
-}
-
-interface QueryMethodConfig {
-  method?: string; // HTTP method: 'GET', 'POST', 'PUT', 'DELETE', etc.
-}
-```
-
-**Returns:**
-
-```ts
-{
-  useQuery: <Name>(name, input?, options?) => UseQueryResult<Output, HttpError>,
-  useMutation: <Name>(name, options?) => UseMutationResult<Output, HttpError, Input>
-}
-```
-
-**Example:**
+// client/analytics-hooks.ts
+import { createHooks } from '@hypequery/react';
+import type { AnalyticsApi } from '../server/api.js';
 
-```ts
-const { useQuery, useMutation } = createHooks<Api>({
-  baseUrl: 'https://api.example.com',
-  headers: {
-    'X-API-Key': process.env.API_KEY,
-  },
-  config: {
-    // Override HTTP method for specific routes
-    uploadFile: { method: 'POST' },
-  },
+export const { useQuery, useMutation } = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  api: {} as AnalyticsApi,
 });
 ```
 
----
-
-### `useQuery(name, input?, options?)`
+Use them inside a component:
 
-Type-safe wrapper around TanStack Query's `useQuery`. Automatically infers input and output types from your API definition.
-
-**Signatures:**
+```tsx
+function RevenuePanel() {
+  const revenue = useQuery('weeklyRevenue', {
+    startDate: '2026-01-01',
+  });
 
-```ts
-// No input required
-useQuery(name: Name)
-useQuery(name: Name, options: QueryOptions)
+  if (revenue.isLoading) return <p>Loading...</p>;
+  if (revenue.error) return <p>{revenue.error.message}</p>;
 
-// Input required
-useQuery(name: Name, input: Input)
-useQuery(name: Name, input: Input, options: QueryOptions)
+  return <pre>{JSON.stringify(revenue.data, null, 2)}</pre>;
+}
 ```
 
-**Parameters:**
-
-- `name` - Query name from your API definition
-- `input` - Query input (typed from your API). Optional if query has no input schema
-- `options` - TanStack Query options (`enabled`, `staleTime`, `refetchInterval`, etc.)
-
-**Returns:** TanStack Query's `UseQueryResult<Output, HttpError>`
+## Dataset And Metric Hooks
 
-**Examples:**
+`createAnalyticsHooks` adds convenience wrappers for semantic endpoint names. Metrics use their endpoint name directly. Dataset endpoints are addressed as `dataset:<name>` in the API type and exposed through `useDataset(name, ...)`.
 
 ```tsx
-// Simple query with no input
-const { data } = useQuery('healthCheck');
+import { createAnalyticsHooks } from '@hypequery/react';
+import type { AnalyticsApi } from '../server/api.js';
 
-// Query with input
-const { data, error, isLoading } = useQuery('getUser', { id: '123' });
+import { manifest } from '../server/api.js'; // serve api.manifest(), serialized
 
-// Query with options
-const { data } = useQuery('getUser', { id: '123' }, {
-  enabled: isLoggedIn,
-  staleTime: 60000,
-  refetchOnWindowFocus: false,
+export const { useMetric, useDataset } = createAnalyticsHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  manifest,
+  metrics: ['revenue', 'averageOrderValue'] as const,
 });
 
-// Query without input but with options
-const { data } = useQuery('healthCheck', { refetchInterval: 5000 });
-```
-
----
-
-### `useMutation(name, options?)`
+function Dashboard() {
+  const revenue = useMetric('revenue', {
+    dimensions: ['country'],
+    filters: [{ field: 'status', operator: 'eq', value: 'completed' }],
+    orderBy: [{ field: 'revenue', direction: 'desc' }],
+    limit: 10,
+  });
 
-Type-safe wrapper around TanStack Query's `useMutation`.
+  const orders = useDataset('orders', {
+    dimensions: ['status'],
+    measures: ['revenue', 'orderCount'],
+  });
 
-**Parameters:**
-
-- `name` - Mutation name from your API definition
-- `options` - TanStack Query mutation options (`onSuccess`, `onError`, `retry`, etc.)
+  return (
+    <pre>
+      {JSON.stringify({ revenue: revenue.data, orders: orders.data }, null, 2)}
+    </pre>
+  );
+}
+```
 
-**Returns:** TanStack Query's `UseMutationResult<Output, HttpError, Input>`
+## Pagination
 
-**Examples:**
+Semantic queries that set a `limit` return `meta.pagination = { limit, offset, hasMore }`
+(`hasMore` is exact — the server over-fetches one row rather than running a count query).
+`useInfiniteQuery`, and the `useInfiniteMetric` / `useInfiniteDataset` wrappers, build on
+this to page through results. They advance the offset automatically and request meta for you.
 
 ```tsx
-// Basic mutation
-const createUser = useMutation('createUser');
-createUser.mutate({ name: 'Alice', email: 'alice@example.com' });
-
-// Mutation with callbacks
-const updateProfile = useMutation('updateProfile', {
-  onSuccess: (data) => {
-    console.log('Profile updated:', data);
-    queryClient.invalidateQueries(['hypequery', 'getProfile']);
-  },
-  onError: (error) => {
-    console.error('Failed to update profile:', error.message);
-  },
-});
+function OrdersTable() {
+  const orders = useInfiniteDataset('orders', {
+    dimensions: ['status'],
+    measures: ['revenue'],
+    limit: 50,
+  });
 
-updateProfile.mutate({ bio: 'New bio' });
+  return (
+    <>
+      {orders.data?.pages.flatMap((page) => page.data).map((row, i) => (
+        <Row key={i} row={row} />
+      ))}
+      <button
+        onClick={() => orders.fetchNextPage()}
+        disabled={!orders.hasNextPage || orders.isFetchingNextPage}
+      >
+        Load more
+      </button>
+    </>
+  );
+}
 ```
 
----
-
-### `queryOptions(options)`
-
-Helper function to explicitly mark an object as query options (not input). Useful when your query input and TanStack Query options have overlapping property names.
+`input.limit` is the page size; `input.offset`, if provided, is the starting offset.
 
-**Parameters:**
+## Route Configuration
 
-- `options` - TanStack Query options object
+Hooks need to know each endpoint's HTTP method and path. There are three ways to
+supply that, in increasing precedence: a route manifest, a runtime `api` object,
+or explicit `config`.
 
-**Returns:** The same object with an internal symbol marker
+### Route manifest (recommended)
 
-**When to use:**
-
-If your API input has properties like `enabled`, `staleTime`, etc., the library might misclassify input as options. Use `queryOptions()` to disambiguate:
-
-```tsx
-// ❌ Ambiguous - could be input or options?
-useQuery('getConfig', { enabled: true, staleTime: 5000 });
+`@hypequery/serve`'s `api.manifest()` returns a serializable map of every
+query/metric/dataset key to its `{ method, path }`. Export it from a server-only
+module and pass it to the hooks — this avoids importing server code into the
+browser bundle while keeping client routes in sync with the server.
 
-// ✅ Explicit - this is input
-useQuery('getConfig', { enabled: true, staleTime: 5000 });
+```ts
+// server side (server-only module)
+export const manifest = api.manifest();
 
-// ✅ Explicit - these are options
-import { queryOptions } from '@hypequery/react';
-useQuery('getConfig', queryOptions({ enabled: true, staleTime: 5000 }));
+// client side
+const { useQuery } = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  manifest,
+});
 ```
 
----
+> Metric and dataset endpoints are POST routes whose paths differ from their map
+> keys (e.g. `dataset:orders` → `POST /api/analytics/datasets/orders/query`). They
+> require a `manifest` (or explicit `config`); calling them without one throws a
+> clear error rather than hitting the wrong URL.
 
-### `HttpError`
+#### Generating the manifest at build time
 
-Custom error class thrown by failed HTTP requests. Extends the standard `Error` class with additional properties.
-
-**Properties:**
+The cleanest way to keep server code out of the browser bundle is to generate a
+JSON file at build time and import that on the client. `api.manifest()` is pure —
+it reads the configured routes and never touches your database — so this step is
+cheap and safe to run in CI.
 
 ```ts
-class HttpError extends Error {
-  readonly status: number;  // HTTP status code (404, 500, etc.)
-  readonly body: unknown;   // Parsed response body (JSON or text)
-}
-```
+// scripts/gen-manifest.ts — run before your client build
+import { writeFileSync } from 'node:fs';
+import { api } from '../server/api.js';
 
-**Usage:**
+writeFileSync('src/generated/manifest.json', JSON.stringify(api.manifest(), null, 2));
+```
 
-```tsx
-const { error } = useQuery('getUser', { id: '123' });
-
-if (error) {
-  console.log(error.message);  // "GET request to /api/getUser failed with status 404"
-  console.log(error.status);   // 404
-  console.log(error.body);     // { message: "User not found" }
-
-  // Type-safe instanceof check
-  if (error instanceof HttpError) {
-    if (error.status === 404) {
-      return <NotFound />;
-    }
+```jsonc
+// package.json
+{
+  "scripts": {
+    "gen:manifest": "tsx scripts/gen-manifest.ts",
+    "build": "npm run gen:manifest && <your client build>"
   }
 }
 ```
 
-**Error handling example:**
-
-```tsx
-import { HttpError } from '@hypequery/react';
-
-function UserProfile({ userId }: { userId: string }) {
-  const { data, error, isLoading } = useQuery('getUser', { id: userId });
-
-  if (isLoading) return <Spinner />;
-
-  if (error instanceof HttpError) {
-    switch (error.status) {
-      case 404:
-        return <NotFound message="User not found" />;
-      case 403:
-        return <Unauthorized />;
-      case 500:
-        return <ServerError details={error.body} />;
-      default:
-        return <Error message={error.message} />;
-    }
-  }
+```ts
+// client side — imports plain JSON, no server code in the bundle
+import manifest from './generated/manifest.json';
 
-  return <div>{data.name}</div>;
-}
+const { useQuery } = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  manifest,
+});
 ```
 
----
+The manifest is derived entirely from your serve config (`basePath`, route keys,
+and `semanticPaths`), so the generated file is deterministic and only changes when
+your API shape does — commit it or regenerate it on every build.
 
-## Advanced Usage
+> `baseUrl` supplies the origin/host; the per-endpoint path comes from the
+> manifest (it already includes the server's `basePath`), so there's no
+> double-prefixing. Keep `baseUrl` aligned with where the API is mounted.
 
-### Custom fetch implementation
+### Explicit config
+
+If a manifest is not available at runtime, pass route config explicitly. This
+overrides any manifest entry.
 
 ```ts
-const { useQuery } = createHooks<Api>({
-  baseUrl: '/api',
-  fetchFn: async (url, init) => {
-    // Add authentication token
-    const token = await getAuthToken();
-    return fetch(url, {
-      ...init,
-      headers: {
-        ...init?.headers,
-        Authorization: `Bearer ${token}`,
-      },
-    });
+const { useQuery } = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  config: {
+    weeklyRevenue: { method: 'POST', path: '/weeklyRevenue' },
   },
 });
 ```
 
-### Default headers
+`path` may be relative to `baseUrl`, absolute within the same origin, or an absolute HTTP URL.
 
-```ts
-const { useQuery } = createHooks<Api>({
-  baseUrl: '/api',
-  headers: {
-    'X-API-Key': process.env.API_KEY,
-    'X-Client-Version': '1.0.0',
-  },
-});
-```
+## Headers & auth
 
-### Dynamic headers
+Pass static headers, or a function (sync or async) invoked per request — handy for
+attaching a fresh/short-lived token.
 
 ```ts
-const { useQuery } = createHooks<Api>({
-  baseUrl: '/api',
-  headers: () => {
-    const key = getTenantKey();
-    return key ? { 'x-tenant-key': key } : {};
-  },
+const hooks = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
 });
 ```
 
-### HTTP method configuration
+Provide `onUnauthorized` to refresh credentials on a `401` and retry the request once
+with freshly resolved headers:
 
 ```ts
-const { useQuery } = createHooks<Api>({
-  baseUrl: '/api',
-  config: {
-    // Override default GET for specific queries
-    refreshCache: { method: 'POST' },
-    deleteUser: { method: 'DELETE' },
+const hooks = createHooks<AnalyticsApi>({
+  baseUrl: '/api/analytics',
+  headers: () => ({ authorization: `Bearer ${tokenStore.access}` }),
+  onUnauthorized: async () => {
+    await tokenStore.refresh(); // throw to abort; resolve to retry once
   },
 });
 ```
 
-### Auto-extract methods from API object
-
-If your API definition includes HTTP method information, pass it to auto-configure:
+## Query Options
 
-```ts
-import { api } from '@/analytics/queries';
+TanStack Query options can be passed as the final argument.
 
-const { useQuery } = createHooks({
-  baseUrl: '/api',
-  api, // Automatically extracts method config from api object
-});
+```tsx
+const result = useQuery(
+  'weeklyRevenue',
+  { startDate: '2026-01-01' },
+  {
+    staleTime: 60_000,
+    refetchOnWindowFocus: false,
+  },
+);
 ```
 
----
-
-## TypeScript
+For no-input queries, use `queryOptions()` when an options object might look like input.
 
-All hooks are fully typed based on your API definition:
+```tsx
+import { queryOptions } from '@hypequery/react';
 
-```ts
-interface Api {
-  getUser: {
-    input: { id: string };
-    output: { name: string; email: string };
-  };
-  weeklyRevenue: {
-    input: { startDate: string };
-    output: { total: number };
-  };
-}
+const result = useQuery('health', queryOptions({
+  staleTime: 30_000,
+}));
+```
 
-const { useQuery } = createHooks<Api>({ baseUrl: '/api' });
+## Mutations
 
-// ✅ TypeScript infers input and output types
-const { data } = useQuery('getUser', { id: '123' });
-//    ^? { name: string; email: string } | undefined
+`useMutation(name)` uses the same endpoint typing and sends requests as `POST` by default unless route config overrides it.
 
-// ❌ TypeScript error: missing required input
-const { data } = useQuery('getUser');
+```tsx
+const refresh = useMutation('refreshReport');
 
-// ❌ TypeScript error: invalid property
-const { data } = useQuery('getUser', { userId: '123' });
+refresh.mutate({ reportId: 'revenue' });
 ```
 
----
+## Notes
+
+- This package does not define datasets. Use `@hypequery/datasets` for semantic definitions.
+- This package does not generate SQL. It calls HTTP routes exposed by `@hypequery/serve`.
+- Dataset relationship JOIN execution is not implied by the React hooks; hooks consume whatever endpoint behavior the server exposes.
 
 ## License
 
-MIT
+Apache-2.0.

package/dist/analyticsHooks.d.ts

@@ -0,0 +1,34 @@
+import type { UseQueryOptions as TanstackUseQueryOptions, UseQueryResult, UseInfiniteQueryResult, InfiniteData } from '@tanstack/react-query';
+import { type CreateHooksConfig } from './createHooks.js';
+import { HttpError } from './errors.js';
+import type { ExtractNames, QueryInput, QueryOutput } from './types.js';
+type DatasetKey<Name extends string> = `dataset:${Name}`;
+type DatasetNamesFromApi<Api> = ExtractNames<Api> extends infer Key ? Key extends `dataset:${infer Name}` ? Name : never : never;
+type QueryKey<Name extends string, Input> = Input extends never ? ['hypequery', Name] : ['hypequery', Name, Input];
+type QueryOptions<Api, Key extends ExtractNames<Api>> = Omit<TanstackUseQueryOptions<QueryOutput<Api, Key>, HttpError, QueryOutput<Api, Key>, QueryKey<Key, QueryInput<Api, Key>>>, 'queryKey' | 'queryFn'>;
+type MetricQueryParams<Api, Key extends ExtractNames<Api>> = QueryInput<Api, Key> extends never ? [name: Key, options?: QueryOptions<Api, Key>] : [name: Key, input: QueryInput<Api, Key>, options?: QueryOptions<Api, Key>];
+type DatasetQueryParams<Api, Name extends DatasetNamesFromApi<Api>> = QueryInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>> extends never ? [name: Name, options?: QueryOptions<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>] : [
+    name: Name,
+    input: QueryInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>,
+    options?: QueryOptions<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>
+];
+export interface CreateAnalyticsHooksConfig<Api extends Record<string, {
+    input: any;
+    output: any;
+}>, TMetrics extends readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[] = readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[]> extends CreateHooksConfig<Api> {
+    metrics?: TMetrics;
+}
+export declare function createAnalyticsHooks<Api extends Record<string, {
+    input: any;
+    output: any;
+}>, const TMetrics extends readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[] = readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[]>(config: CreateAnalyticsHooksConfig<Api, TMetrics>): {
+    readonly useMetric: <Name extends TMetrics extends readonly (infer U)[] ? U extends string ? U : never : Exclude<ExtractNames<Api>, `dataset:${string}`>>(...args: MetricQueryParams<Api, Name>) => UseQueryResult<QueryOutput<Api, Name>, HttpError>;
+    readonly useDataset: <Name extends DatasetNamesFromApi<Api>>(...args: DatasetQueryParams<Api, Name>) => UseQueryResult<QueryOutput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>, HttpError>;
+    readonly useInfiniteMetric: <Name extends TMetrics extends readonly (infer U)[] ? U extends string ? U : never : Exclude<ExtractNames<Api>, `dataset:${string}`>>(name: Name, input: QueryInput<Api, Name>, options?: Parameters<(<Name_1 extends Extract<keyof Api, string>>(name: Name_1, input: QueryInput<Api, Name_1>, options?: Omit<import("@tanstack/react-query").UseInfiniteQueryOptions<QueryOutput<Api, Name_1>, HttpError, InfiniteData<QueryOutput<Api, Name_1>, number>, QueryInput<Api, Name_1> extends never ? ["hypequery", Name_1] : ["hypequery", Name_1, QueryInput<Api, Name_1>], number>, "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"> | undefined) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name_1>, number>, HttpError>)>[2]) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name>, number>, HttpError>;
+    readonly useInfiniteDataset: <Name extends DatasetNamesFromApi<Api>>(name: Name, input: QueryInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>, options?: Parameters<(<Name_1 extends Extract<keyof Api, string>>(name: Name_1, input: QueryInput<Api, Name_1>, options?: Omit<import("@tanstack/react-query").UseInfiniteQueryOptions<QueryOutput<Api, Name_1>, HttpError, InfiniteData<QueryOutput<Api, Name_1>, number>, QueryInput<Api, Name_1> extends never ? ["hypequery", Name_1] : ["hypequery", Name_1, QueryInput<Api, Name_1>], number>, "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"> | undefined) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name_1>, number>, HttpError>)>[2]) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>, number>, HttpError>;
+    readonly useQuery: <Name extends Extract<keyof Api, string>>(...args: QueryInput<Api, Name> extends never ? [name: Name, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined] : [name: Name, input: QueryInput<Api, Name>, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined]) => UseQueryResult<QueryOutput<Api, Name>, HttpError>;
+    readonly useMutation: <Name extends Extract<keyof Api, string>>(name: Name, options?: Omit<import("@tanstack/react-query").UseMutationOptions<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>, unknown>, "mutationFn"> | undefined) => import("@tanstack/react-query").UseMutationResult<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>>;
+    readonly useInfiniteQuery: <Name extends Extract<keyof Api, string>>(name: Name, input: QueryInput<Api, Name>, options?: Omit<import("@tanstack/react-query").UseInfiniteQueryOptions<QueryOutput<Api, Name>, HttpError, InfiniteData<QueryOutput<Api, Name>, number>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>], number>, "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"> | undefined) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name>, number>, HttpError>;
+};
+export {};
+//# sourceMappingURL=analyticsHooks.d.ts.map

package/dist/analyticsHooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsHooks.d.ts","sourceRoot":"","sources":["../src/analyticsHooks.tsx"],"names":[],"mappings":"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"}

package/dist/analyticsHooks.js

@@ -0,0 +1,27 @@
+import { createHooks } from './createHooks.js';
+export function createAnalyticsHooks(config) {
+    const hooks = createHooks(config);
+    function useMetric(...args) {
+        const [name, ...rest] = args;
+        return hooks.useQuery(name, ...rest);
+    }
+    function useDataset(...args) {
+        const [name, ...rest] = args;
+        const key = `dataset:${String(name)}`;
+        return hooks.useQuery(key, ...rest);
+    }
+    function useInfiniteMetric(name, input, options) {
+        return hooks.useInfiniteQuery(name, input, options);
+    }
+    function useInfiniteDataset(name, input, options) {
+        const key = `dataset:${String(name)}`;
+        return hooks.useInfiniteQuery(key, input, options);
+    }
+    return {
+        ...hooks,
+        useMetric,
+        useDataset,
+        useInfiniteMetric,
+        useInfiniteDataset,
+    };
+}

package/dist/analyticsHooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyticsHooks.test.d.ts.map

package/dist/analyticsHooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyticsHooks.test.d.ts","sourceRoot":"","sources":["../src/analyticsHooks.test.tsx"],"names":[],"mappings":""}

package/dist/analyticsHooks.test.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createAnalyticsHooks } from './analyticsHooks.js';
+function createWrapper() {
+    const queryClient = new QueryClient({
+        defaultOptions: {
+            queries: { retry: false },
+        },
+    });
+    return ({ children }) => (_jsx(QueryClientProvider, { client: queryClient, children: children }));
+}
+function mockSuccessResponse(data) {
+    return {
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(data),
+    };
+}
+describe('createAnalyticsHooks', () => {
+    const fetchMock = vi.fn();
+    beforeEach(() => {
+        fetchMock.mockReset();
+    });
+    it('queries metrics through useMetric with metric names only', async () => {
+        fetchMock.mockResolvedValue(mockSuccessResponse({ data: [{ totalRevenue: 42 }] }));
+        const { useMetric } = createAnalyticsHooks({
+            baseUrl: '/api/analytics',
+            fetchFn: fetchMock,
+            metrics: ['totalRevenue', 'monthlyRevenue'],
+            config: {
+                totalRevenue: { method: 'POST', path: '/api/analytics/metrics/totalRevenue' },
+            },
+        });
+        const { result } = renderHook(() => useMetric('totalRevenue', { dimensions: ['country'] }), { wrapper: createWrapper() });
+        await waitFor(() => {
+            expect(result.current.data).toEqual({ data: [{ totalRevenue: 42 }] });
+        });
+        expect(fetchMock).toHaveBeenCalledWith('/api/analytics/metrics/totalRevenue', expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ dimensions: ['country'] }),
+        }));
+    });
+    it('queries datasets through useDataset without exposing dataset: keys', async () => {
+        fetchMock.mockResolvedValue(mockSuccessResponse({ data: [{ country: 'US', revenue: 120 }] }));
+        const { useDataset } = createAnalyticsHooks({
+            baseUrl: '/api/analytics',
+            fetchFn: fetchMock,
+            metrics: [],
+            config: {
+                'dataset:orders': { method: 'POST', path: '/api/analytics/datasets/orders/query' },
+            },
+        });
+        const { result } = renderHook(() => useDataset('orders', { dimensions: ['country'], measures: ['revenue'] }), { wrapper: createWrapper() });
+        await waitFor(() => {
+            expect(result.current.data).toEqual({ data: [{ country: 'US', revenue: 120 }] });
+        });
+        expect(fetchMock).toHaveBeenCalledWith('/api/analytics/datasets/orders/query', expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ dimensions: ['country'], measures: ['revenue'] }),
+        }));
+    });
+    it('supports metric names from the declared semantic metric list', async () => {
+        fetchMock.mockResolvedValue(mockSuccessResponse({ data: [{ period: '2025-01-01', monthlyRevenue: 90 }] }));
+        const { useMetric } = createAnalyticsHooks({
+            baseUrl: '/api/analytics',
+            fetchFn: fetchMock,
+            metrics: ['totalRevenue', 'monthlyRevenue'],
+            config: {
+                monthlyRevenue: { method: 'POST', path: '/api/analytics/metrics/monthlyRevenue' },
+            },
+        });
+        const { result } = renderHook(() => useMetric('monthlyRevenue', { by: 'month' }), { wrapper: createWrapper() });
+        await waitFor(() => {
+            expect(result.current.data).toEqual({ data: [{ period: '2025-01-01', monthlyRevenue: 90 }] });
+        });
+    });
+    it('resolves semantic config paths against an absolute baseUrl host', async () => {
+        fetchMock.mockResolvedValue(mockSuccessResponse({ data: [{ totalRevenue: 42 }] }));
+        const { useMetric } = createAnalyticsHooks({
+            baseUrl: 'https://api.example.com/hypequery',
+            fetchFn: fetchMock,
+            metrics: ['totalRevenue', 'monthlyRevenue'],
+            config: {
+                totalRevenue: { method: 'POST', path: '/api/analytics/metrics/totalRevenue' },
+            },
+        });
+        const { result } = renderHook(() => useMetric('totalRevenue', { dimensions: ['country'] }), { wrapper: createWrapper() });
+        await waitFor(() => {
+            expect(result.current.data).toEqual({ data: [{ totalRevenue: 42 }] });
+        });
+        expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/api/analytics/metrics/totalRevenue', expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ dimensions: ['country'] }),
+        }));
+    });
+});

package/dist/createHooks.d.ts

@@ -1,19 +1,47 @@
-import { type UseQueryOptions as TanstackUseQueryOptions, type UseMutationOptions as TanstackUseMutationOptions, type UseMutationResult, type UseQueryResult } from '@tanstack/react-query';
+import { type UseQueryOptions as TanstackUseQueryOptions, type UseMutationOptions as TanstackUseMutationOptions, type UseInfiniteQueryOptions as TanstackUseInfiniteQueryOptions, type UseMutationResult, type UseQueryResult, type UseInfiniteQueryResult, type InfiniteData } from '@tanstack/react-query';
 import type { ExtractNames, QueryInput, QueryOutput } from './types.js';
 import { HttpError } from './errors.js';
 export interface QueryMethodConfig {
     method?: string;
+    path?: string;
 }
+/** A single route as produced by `@hypequery/serve`'s `api.manifest()`. */
+export interface RouteManifestEntry {
+    method?: string;
+    path?: string;
+}
+/**
+ * Map of query/metric/dataset keys to their HTTP method and full path. Pair
+ * with `InferAPIType` and `api.manifest()` from `@hypequery/serve` to resolve
+ * routes on the client without importing server code into the bundle.
+ */
+export type RouteManifest = Record<string, RouteManifestEntry>;
 type HeaderMap = Record<string, string | undefined>;
-type HeadersInput = HeaderMap | (() => HeaderMap);
+type HeadersInput = HeaderMap | (() => HeaderMap | Promise<HeaderMap>);
 export interface CreateHooksConfig<TApi = Record<string, {
     input: unknown;
     output: unknown;
 }>> {
     baseUrl: string;
     fetchFn?: typeof fetch;
+    /**
+     * Static headers, or a (optionally async) function returning headers. The
+     * function is invoked per request, so it can supply a fresh/short-lived token.
+     */
     headers?: HeadersInput;
     config?: Record<string, QueryMethodConfig>;
+    /**
+     * Route manifest from `@hypequery/serve`'s `api.manifest()`. Resolves the
+     * method and full path for each key — required for metric/dataset endpoints,
+     * which are POST routes whose paths differ from their map keys.
+     */
+    manifest?: RouteManifest;
+    /**
+     * Called when a request returns 401. Use it to refresh credentials (e.g. a
+     * token). If it resolves without throwing, the request is retried once with
+     * freshly resolved headers.
+     */
+    onUnauthorized?: () => void | Promise<void>;
     api?: TApi;
 }
 declare const OPTIONS_SYMBOL: unique symbol;
@@ -26,6 +54,7 @@ export declare function createHooks<Api extends Record<string, {
 }>>(config: CreateHooksConfig<Api>): {
     readonly useQuery: <Name extends ExtractNames<Api>>(...args: QueryInput<Api, Name> extends never ? [name: Name, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined] : [name: Name, input: QueryInput<Api, Name>, options?: Omit<TanstackUseQueryOptions<QueryOutput<Api, Name>, HttpError, QueryOutput<Api, Name>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined]) => UseQueryResult<QueryOutput<Api, Name>, HttpError>;
     readonly useMutation: <Name extends ExtractNames<Api>>(name: Name, options?: Omit<TanstackUseMutationOptions<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>, unknown>, "mutationFn">) => UseMutationResult<QueryOutput<Api, Name>, HttpError, QueryInput<Api, Name>>;
+    readonly useInfiniteQuery: <Name extends ExtractNames<Api>>(name: Name, input: QueryInput<Api, Name>, options?: Omit<TanstackUseInfiniteQueryOptions<QueryOutput<Api, Name>, HttpError, InfiniteData<QueryOutput<Api, Name>, number>, QueryInput<Api, Name> extends never ? ["hypequery", Name] : ["hypequery", Name, QueryInput<Api, Name>], number>, "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam">) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name>, number>, HttpError>;
 };
 export {};
 //# sourceMappingURL=createHooks.d.ts.map

package/dist/createHooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createHooks.d.ts","sourceRoot":"","sources":["../src/createHooks.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,IAAI,uBAAuB,EAC/C,KAAK,kBAAkB,IAAI,0BAA0B,EACrD,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AACpD,KAAK,YAAY,GAAG,SAAS,GAAG,CAAC,MAAM,SAAS,CAAC,CAAC;AAElD,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,QAAA,MAAM,cAAc,eAAkC,CAAC;AAEvD,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAEtF;AAqED,wBAAgB,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,EACjF,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC;wBAmEZ,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,+kBAE7C,cAAc,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC;2BAwC/B,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,QAC3C,IAAI,kIAET,iBAAiB,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;EAW/E"}
+{"version":3,"file":"createHooks.d.ts","sourceRoot":"","sources":["../src/createHooks.tsx"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,eAAe,IAAI,uBAAuB,EAC/C,KAAK,kBAAkB,IAAI,0BAA0B,EACrD,KAAK,uBAAuB,IAAI,+BAA+B,EAC/D,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUxC,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAE/D,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AACpD,KAAK,YAAY,GACb,SAAS,GACT,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AAE3C,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,QAAA,MAAM,cAAc,eAAkC,CAAC;AAEvD,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;CAAE,CAEtF;AAqGD,wBAAgB,WAAW,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,EACjF,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC;wBAgGZ,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,+kBAE7C,cAAc,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC;2BAwC/B,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,QAC3C,IAAI,kIAET,iBAAiB,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gCAwBpD,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,QAChD,IAAI,SACH,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,yTAE3B,sBAAsB,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,SAAS,CAAC;EA4BnF"}

package/dist/createHooks.js

@@ -1,4 +1,4 @@
-import { useQuery as useTanstackQuery, useMutation as useTanstackMutation, } from '@tanstack/react-query';
+import { useQuery as useTanstackQuery, useMutation as useTanstackMutation, useInfiniteQuery as useTanstackInfiniteQuery, } from '@tanstack/react-query';
 import { HttpError } from './errors.js';
 const OPTIONS_SYMBOL = Symbol.for('hypequery-options');
 export function queryOptions(opts) {
@@ -7,12 +7,19 @@ export function queryOptions(opts) {
 const normalizeMethodConfig = (source) => {
     if (!source)
         return {};
-    return Object.fromEntries(Object.entries(source).map(([key, value]) => [key, { method: value.method ?? 'GET' }]));
+    return Object.fromEntries(Object.entries(source).map(([key, value]) => [key, { method: value.method ?? 'GET', path: value.path }]));
 };
 const deriveMethodConfig = (api) => {
     if (typeof api !== 'object' || api === null) {
         return {};
     }
+    // Preferred: the serve API exposes a manifest() with full method + path.
+    if (typeof api.manifest === 'function') {
+        const manifest = api.manifest();
+        if (manifest && typeof manifest === 'object') {
+            return normalizeMethodConfig(manifest);
+        }
+    }
     if ('_routeConfig' in api &&
         typeof api._routeConfig === 'object' &&
         api._routeConfig !== null) {
@@ -25,11 +32,28 @@ const deriveMethodConfig = (api) => {
     }
     return {};
 };
-const buildUrl = (baseUrl, name) => {
+const isAbsoluteHttpUrl = (value) => /^https?:\/\//.test(value);
+const ensureTrailingSlash = (value) => value.endsWith('/') ? value : `${value}/`;
+const buildUrl = (baseUrl, name, path) => {
+    if (path) {
+        if (isAbsoluteHttpUrl(path)) {
+            return path;
+        }
+        if (isAbsoluteHttpUrl(baseUrl)) {
+            return new URL(path, ensureTrailingSlash(baseUrl)).toString();
+        }
+        if (path.startsWith('/')) {
+            return path;
+        }
+        if (!baseUrl) {
+            throw new Error('baseUrl is required');
+        }
+        return `${ensureTrailingSlash(baseUrl)}${path}`;
+    }
     if (!baseUrl) {
         throw new Error('baseUrl is required');
     }
-    return baseUrl.endsWith('/') ? `${baseUrl}${name}` : `${baseUrl}/${name}`;
+    return `${ensureTrailingSlash(baseUrl)}${name}`;
 };
 const parseResponse = async (res) => {
     const text = await res.text();
@@ -52,18 +76,31 @@ const looksLikeQueryOptions = (value) => {
     const matches = optionKeys.filter((key) => key in value).length;
     return matches >= 2;
 };
-const resolveHeaders = (headers) => {
+const resolveHeaders = async (headers) => {
     if (!headers)
         return {};
-    const raw = typeof headers === 'function' ? headers() : headers;
+    const raw = typeof headers === 'function' ? await headers() : headers;
     return Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== undefined));
 };
 export function createHooks(config) {
-    const { baseUrl, fetchFn = fetch, headers = {}, config: explicitConfig = {}, api } = config;
-    const finalConfig = { ...deriveMethodConfig(api), ...explicitConfig };
-    const fetchQuery = async (name, input, defaultMethod = 'GET') => {
-        const url = buildUrl(baseUrl, name);
-        const method = finalConfig[name]?.method ?? defaultMethod;
+    const { baseUrl, fetchFn = fetch, headers = {}, config: explicitConfig = {}, manifest, onUnauthorized, api } = config;
+    // Precedence: explicit config > manifest > derived from a runtime api object.
+    const finalConfig = {
+        ...deriveMethodConfig(api),
+        ...(manifest ? normalizeMethodConfig(manifest) : {}),
+        ...explicitConfig,
+    };
+    const fetchQuery = async (name, input, defaultMethod = 'GET', extraHeaders) => {
+        const methodConfig = finalConfig[name];
+        // Semantic endpoints (dataset:<name>) live at paths that differ from their
+        // map key, so without a resolved path we'd call the wrong URL. Fail loudly
+        // instead of silently requesting `${baseUrl}/dataset:<name>`.
+        if (name.includes(':') && !methodConfig?.path) {
+            throw new Error(`No route configured for "${name}". Pass \`manifest\` (from the serve ` +
+                `api.manifest()) or an explicit \`config\` entry to createHooks().`);
+        }
+        const url = buildUrl(baseUrl, name, methodConfig?.path);
+        const method = methodConfig?.method ?? defaultMethod;
         let finalUrl = url;
         let body;
         if (method === 'GET' && input && typeof input === 'object') {
@@ -84,15 +121,24 @@ export function createHooks(config) {
         else if (input !== undefined) {
             body = JSON.stringify(input);
         }
-        const resolvedHeaders = resolveHeaders(headers);
-        const res = await fetchFn(finalUrl, {
-            method,
-            headers: {
-                ...resolvedHeaders,
-                ...(body ? { 'content-type': 'application/json' } : {}),
-            },
-            body,
-        });
+        const attempt = async () => {
+            const resolvedHeaders = await resolveHeaders(headers);
+            return fetchFn(finalUrl, {
+                method,
+                headers: {
+                    ...resolvedHeaders,
+                    ...(extraHeaders ?? {}),
+                    ...(body ? { 'content-type': 'application/json' } : {}),
+                },
+                body,
+            });
+        };
+        let res = await attempt();
+        // On 401, give the caller a chance to refresh credentials and retry once.
+        if (res.status === 401 && onUnauthorized) {
+            await onUnauthorized();
+            res = await attempt();
+        }
         if (!res.ok) {
             const errorBody = await parseResponse(res);
             throw new HttpError(`${method} request to ${finalUrl} failed with status ${res.status}`, res.status, errorBody);
@@ -133,8 +179,31 @@ export function createHooks(config) {
             ...options,
         });
     }
+    /**
+     * Offset-paginated query for semantic endpoints. Pages are advanced using the
+     * `meta.pagination` returned by the server (the request opts into meta via the
+     * `x-include-meta` header). `input.limit` is the page size; `input.offset`, if
+     * provided, is the starting offset.
+     */
+    function useInfiniteQuery(name, input, options) {
+        const initialOffset = input?.offset ?? 0;
+        const queryKey = ['hypequery', name, input];
+        return useTanstackInfiniteQuery({
+            queryKey,
+            initialPageParam: initialOffset,
+            queryFn: ({ pageParam }) => fetchQuery(name, { ...input, offset: pageParam }, 'POST', { 'x-include-meta': 'true' }),
+            getNextPageParam: (lastPage) => {
+                const pagination = lastPage.meta?.pagination;
+                if (!pagination || !pagination.hasMore)
+                    return undefined;
+                return pagination.offset + pagination.limit;
+            },
+            ...(options ?? {}),
+        });
+    }
     return {
         useQuery,
         useMutation,
+        useInfiniteQuery,
     };
 }

package/dist/createHooks.test.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { renderHook, waitFor } from '@testing-library/react';
+import { renderHook, waitFor, act } from '@testing-library/react';
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { createHooks, queryOptions } from './createHooks.js';
 import { HttpError } from './errors.js';
@@ -93,6 +93,57 @@ describe('createHooks', () => {
             expect(fetchMock.mock.calls[0][1]?.headers).toMatchObject({ 'x-token': 'first' });
             expect(fetchMock.mock.calls[1][1]?.headers).toMatchObject({ 'x-token': 'second' });
         });
+        it('supports an async header factory', async () => {
+            fetchMock.mockResolvedValue(mockSuccessResponse({ name: 'User' }));
+            const { useQuery } = createHooks({
+                baseUrl: 'https://example.com/api',
+                fetchFn: fetchMock,
+                headers: async () => ({ authorization: 'Bearer fresh-token' }),
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '1' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock.mock.calls[0][1]?.headers).toMatchObject({ authorization: 'Bearer fresh-token' });
+        });
+        it('calls onUnauthorized and retries once on 401', async () => {
+            fetchMock
+                .mockResolvedValueOnce(mockErrorResponse(401, { error: 'expired' }))
+                .mockResolvedValueOnce(mockSuccessResponse({ name: 'User' }));
+            let token = 'stale';
+            const onUnauthorized = vi.fn(async () => { token = 'refreshed'; });
+            const { useQuery } = createHooks({
+                baseUrl: 'https://example.com/api',
+                fetchFn: fetchMock,
+                headers: () => ({ authorization: `Bearer ${token}` }),
+                onUnauthorized,
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '1' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(onUnauthorized).toHaveBeenCalledTimes(1);
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            // The retry uses freshly resolved headers.
+            expect(fetchMock.mock.calls[1][1]?.headers).toMatchObject({ authorization: 'Bearer refreshed' });
+            expect(result.current.data).toEqual({ name: 'User' });
+        });
+        it('throws after a single 401 retry still fails', async () => {
+            fetchMock.mockResolvedValue(mockErrorResponse(401, { error: 'nope' }));
+            const onUnauthorized = vi.fn(async () => { });
+            const { useQuery } = createHooks({
+                baseUrl: 'https://example.com/api',
+                fetchFn: fetchMock,
+                onUnauthorized,
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '1' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isError).toBe(true));
+            expect(onUnauthorized).toHaveBeenCalledTimes(1);
+            expect(fetchMock).toHaveBeenCalledTimes(2);
+            expect(result.current.error?.status).toBe(401);
+        });
     });
     describe('HTTP Method Handling', () => {
         const fetchMock = vi.fn();
@@ -186,6 +237,108 @@ describe('createHooks', () => {
             await waitFor(() => expect(result.current.isSuccess).toBe(true));
             expect(fetchMock).toHaveBeenCalledWith('https://example.com/api/getUser', expect.objectContaining({ method: 'POST' }));
         });
+        it('resolves root-relative config paths against an absolute baseUrl host', async () => {
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com/hypequery',
+                fetchFn: fetchMock,
+                config: {
+                    getUser: { method: 'POST', path: '/api/analytics/queries/getUser' },
+                },
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '123' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/api/analytics/queries/getUser', expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify({ id: '123' }),
+            }));
+        });
+        it('resolves relative config paths against baseUrl', async () => {
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com/hypequery',
+                fetchFn: fetchMock,
+                config: {
+                    getUser: { method: 'POST', path: 'queries/getUser' },
+                },
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '123' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/hypequery/queries/getUser', expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify({ id: '123' }),
+            }));
+        });
+    });
+    describe('Route manifest', () => {
+        const fetchMock = vi.fn();
+        beforeEach(() => {
+            fetchMock.mockReset();
+            fetchMock.mockResolvedValue(mockSuccessResponse({ success: true }));
+        });
+        it('resolves method and path from a manifest', async () => {
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com',
+                fetchFn: fetchMock,
+                manifest: {
+                    getUser: { method: 'POST', path: '/api/analytics/metrics/getUser' },
+                },
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '123' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/api/analytics/metrics/getUser', expect.objectContaining({
+                method: 'POST',
+                body: JSON.stringify({ id: '123' }),
+            }));
+        });
+        it('lets explicit config override the manifest', async () => {
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com',
+                fetchFn: fetchMock,
+                manifest: {
+                    getUser: { method: 'POST', path: '/manifest/getUser' },
+                },
+                config: {
+                    getUser: { method: 'POST', path: '/override/getUser' },
+                },
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '123' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/override/getUser', expect.objectContaining({ method: 'POST' }));
+        });
+        it('derives method config from an api object exposing manifest()', async () => {
+            const mockApi = {
+                manifest: () => ({
+                    getUser: { method: 'PATCH', path: '/api/analytics/queries/getUser' },
+                }),
+            };
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com',
+                fetchFn: fetchMock,
+                api: mockApi,
+            });
+            const { result } = renderHook(() => useQuery('getUser', { id: '123' }), {
+                wrapper: createWrapper(),
+            });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/api/analytics/queries/getUser', expect.objectContaining({ method: 'PATCH' }));
+        });
+        it('throws for an unresolved semantic (dataset:) key', async () => {
+            const { useQuery } = createHooks({
+                baseUrl: 'https://api.example.com',
+                fetchFn: fetchMock,
+            });
+            const { result } = renderHook(() => useQuery('dataset:orders', { dimensions: ['country'] }), { wrapper: createWrapper() });
+            await waitFor(() => expect(result.current.isError).toBe(true));
+            expect(result.current.error?.message).toContain('No route configured for "dataset:orders"');
+            expect(fetchMock).not.toHaveBeenCalled();
+        });
     });
     describe('Query Parameter Serialization', () => {
         const fetchMock = vi.fn();
@@ -581,4 +734,39 @@ describe('createHooks', () => {
             await expect(result.current.mutateAsync({ id: '123', name: 'John' })).rejects.toThrow();
         });
     });
+    describe('useInfiniteQuery', () => {
+        const fetchMock = vi.fn();
+        beforeEach(() => {
+            fetchMock.mockReset();
+        });
+        it('paginates using meta.pagination and advances the offset', async () => {
+            fetchMock
+                .mockResolvedValueOnce(mockSuccessResponse({
+                data: [{ id: 'a' }],
+                meta: { pagination: { limit: 1, offset: 0, hasMore: true } },
+            }))
+                .mockResolvedValueOnce(mockSuccessResponse({
+                data: [{ id: 'b' }],
+                meta: { pagination: { limit: 1, offset: 1, hasMore: false } },
+            }));
+            const { useInfiniteQuery } = createHooks({
+                baseUrl: 'https://example.com/api',
+                fetchFn: fetchMock,
+                config: { listItems: { method: 'POST', path: '/datasets/items/query' } },
+            });
+            const { result } = renderHook(() => useInfiniteQuery('listItems', { tags: [], limit: 1 }), { wrapper: createWrapper() });
+            await waitFor(() => expect(result.current.isSuccess).toBe(true));
+            // First page requests offset 0 and opts into meta.
+            expect(fetchMock.mock.calls[0][1]?.headers['x-include-meta']).toBe('true');
+            expect(fetchMock.mock.calls[0][1]?.body).toBe(JSON.stringify({ tags: [], limit: 1, offset: 0 }));
+            expect(result.current.hasNextPage).toBe(true);
+            await act(async () => {
+                await result.current.fetchNextPage();
+            });
+            await waitFor(() => expect(result.current.hasNextPage).toBe(false));
+            // Second page advances offset by the page size.
+            expect(fetchMock.mock.calls[1][1]?.body).toBe(JSON.stringify({ tags: [], limit: 1, offset: 1 }));
+            expect(result.current.data?.pages).toHaveLength(2);
+        });
+    });
 });

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { createHooks, queryOptions } from './createHooks.js';
+export { createAnalyticsHooks } from './analyticsHooks.js';
 export { HttpError } from './errors.js';
 export type { QueryInput, QueryOutput, HttpMethod } from './types.js';
 export type { CreateHooksConfig, QueryMethodConfig } from './createHooks.js';
+export type { CreateAnalyticsHooksConfig } from './analyticsHooks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createHooks, queryOptions } from './createHooks.js';
+export { createAnalyticsHooks } from './analyticsHooks.js';
 export { HttpError } from './errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/react",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "React hooks for consuming hypequery APIs",
   "type": "module",
   "main": "./dist/index.js",