@hypequery/react 0.1.1 → 0.3.0

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();
@@ -378,7 +531,7 @@ describe('createHooks', () => {
             expect(fetchMock).toHaveBeenCalled();
             fetchMock.mockClear();
             // Options object should disable the query
-            const { result: result2 } = renderHook(() => useQuery('noInput', { enabled: false, staleTime: 1000 }), { wrapper: createWrapper() });
+            renderHook(() => useQuery('noInput', { enabled: false, staleTime: 1000 }), { wrapper: createWrapper() });
             expect(fetchMock).not.toHaveBeenCalled();
         });
         it('uses queryOptions() helper for explicit option marking', async () => {
@@ -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/dist/types.d.ts

@@ -1,9 +1,62 @@
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-export type ExtractNames<Api> = Extract<keyof Api, string>;
+export type KnownStringKeys<T> = {
+    [K in keyof T]: string extends K ? never : K extends string ? K : never;
+}[keyof T];
+export type ExtractNames<Api> = [KnownStringKeys<Api>] extends [never] ? Extract<keyof Api, string> : KnownStringKeys<Api>;
 export type QueryInput<Api, Name extends ExtractNames<Api>> = Api[Name] extends {
     input: infer Input;
 } ? Input : never;
 export type QueryOutput<Api, Name extends ExtractNames<Api>> = Api[Name] extends {
     output: infer Output;
 } ? Output : never;
+type SemanticInfo<Api, Name extends ExtractNames<Api>> = Api[Name] extends {
+    readonly __hypequerySemantic?: infer Info;
+} ? NonNullable<Info> : never;
+type DimensionValue<TDefinition> = TDefinition extends {
+    fieldType: 'string';
+} ? string : TDefinition extends {
+    fieldType: 'number';
+} ? number : TDefinition extends {
+    fieldType: 'boolean';
+} ? boolean : TDefinition extends {
+    fieldType: 'timestamp';
+} ? string : unknown;
+type SelectedDimensions<TDimensions, TInput> = TInput extends {
+    dimensions: readonly (infer TName)[];
+} ? Extract<TName, KnownStringKeys<TDimensions>> : never;
+type SelectedMeasures<TMeasures, TInput> = TInput extends {
+    measures: readonly (infer TName)[];
+} ? Extract<TName, KnownStringKeys<TMeasures>> : KnownStringKeys<TMeasures>;
+type PeriodSelection<TInput> = TInput extends {
+    by: string;
+} ? {
+    period?: string;
+} : {};
+type WithTypedData<TOutput, TRow> = Omit<TOutput, 'data'> & {
+    data: TRow[];
+};
+type DatasetOutputForInput<TInfo, TInput, TFallback> = TInfo extends {
+    kind: 'dataset';
+    dimensions: infer TDimensions;
+    measures: infer TMeasures;
+} ? WithTypedData<TFallback, {
+    [K in SelectedDimensions<TDimensions, TInput>]?: DimensionValue<TDimensions[K]>;
+} & {
+    [K in SelectedMeasures<TMeasures, TInput>]?: number;
+} & PeriodSelection<TInput>> : TFallback;
+type MetricOutputForInput<TInfo, TInput, TFallback> = TInfo extends {
+    kind: 'metric';
+    dimensions: infer TDimensions;
+    metricName: infer TMetricName extends string;
+} ? WithTypedData<TFallback, {
+    [K in SelectedDimensions<TDimensions, TInput>]?: DimensionValue<TDimensions[K]>;
+} & {
+    [K in TMetricName]?: number;
+} & PeriodSelection<TInput>> : TFallback;
+export type QueryOutputForInput<Api, Name extends ExtractNames<Api>, TInput> = SemanticInfo<Api, Name> extends infer Info ? Info extends {
+    kind: 'dataset';
+} ? DatasetOutputForInput<Info, TInput, QueryOutput<Api, Name>> : Info extends {
+    kind: 'metric';
+} ? MetricOutputForInput<Info, TInput, QueryOutput<Api, Name>> : QueryOutput<Api, Name> : QueryOutput<Api, Name>;
+export {};
 //# sourceMappingURL=types.d.ts.map