@hypequery/react 0.5.0 → 0.6.0

package/README.md

@@ -1,307 +1,128 @@
 # @hypequery/react
 
-React hooks for typed Hypequery HTTP endpoints, built on TanStack Query.
+Typed React hooks for ClickHouse analytics, powered by TanStack Query.
 
-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.
+`@hypequery/react` carries `@hypequery/serve` contracts into React and Next.js. Query names, inputs, metrics, dataset fields, and response rows stay inferred from the server, so frontend analytics do not drift into a second set of hand-written types.
+
+Use it for product dashboards, embedded analytics, customer reporting, and multi-tenant SaaS metrics.
 
 ## Install
 
 ```bash
 npm install @hypequery/react @tanstack/react-query
-# or
-pnpm add @hypequery/react @tanstack/react-query
 ```
 
-## Quick Start
-
-Given a serve 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',
-});
-
-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(),
-});
-
-export const api = serve({
-  queries: { weeklyRevenue },
-});
+## Create hooks from your API
 
-api.route('/weeklyRevenue', api.queries.weeklyRevenue);
+Generate a small route manifest during the build:
 
-export type AnalyticsApi = typeof api;
+```bash
+npx hypequery generate:manifest analytics/api.ts \
+  --output src/generated/hypequery-manifest.json
 ```
 
-Create hooks on the client:
+## Configure Once With `HypequeryProvider`
+
+For hosted APIs and generated clients, create hooks without transport
+configuration. A provider supplies one client to the application and includes a
+TanStack Query provider by default.
 
 ```tsx
-// client/analytics-hooks.ts
+// client/hypequery.ts
 import { createHooks } from '@hypequery/react';
 import type { AnalyticsApi } from '../server/api.js';
 
-export const { useQuery, useMutation } = createHooks<AnalyticsApi>({
-  baseUrl: '/api/analytics',
-  api: {} as AnalyticsApi,
-});
+export const { useQuery, useMutation } = createHooks<AnalyticsApi>();
 ```
 
-Use them inside a component:
-
 ```tsx
-function RevenuePanel() {
-  const revenue = useQuery('weeklyRevenue', {
-    startDate: '2026-01-01',
-  });
+// app/providers.tsx
+'use client';
+
+import {
+  createHypequeryClient,
+  HypequeryProvider,
+} from '@hypequery/react';
+import type { ReactNode } from 'react';
+import type { AnalyticsApi } from '../server/api.js';
+import manifest from '../generated/hypequery-manifest.json';
 
-  if (revenue.isLoading) return <p>Loading...</p>;
-  if (revenue.error) return <p>{revenue.error.message}</p>;
+const client = createHypequeryClient<AnalyticsApi>({
+  baseUrl: 'https://acme.hypequery.cloud/v1/analytics/production',
+  manifest,
+  // Resolve a short-lived browser token. Never expose a server API key here.
+  token: async () => tokenStore.get(),
+  onUnauthorized: () => tokenStore.refresh(),
+});
 
-  return <pre>{JSON.stringify(revenue.data, null, 2)}</pre>;
+export function Providers({ children }: { children: ReactNode }) {
+  return <HypequeryProvider client={client}>{children}</HypequeryProvider>;
 }
 ```
 
-## Dataset And Metric Hooks
+Applications that already own a TanStack Query client can pass it through the
+`queryClient` prop so Hypequery shares the existing cache.
+
+Each client instance receives an isolated cache scope. Create a new client when
+the deployment, tenant, or authenticated user changes. A deterministic
+`cacheKey` may be supplied when the same security context must retain cache data
+across equivalent client instances.
+
+## Create Dataset And Metric Hooks
 
 `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
 import { createAnalyticsHooks } from '@hypequery/react';
-import type { InferApiType } from '@hypequery/serve';
-import type { api } from '../server/api.js';
-
-import manifest from './hypequery-manifest.json';
-
-type AnalyticsApi = InferApiType<typeof api>;
-
-export const { useMetric, useDataset } = createAnalyticsHooks<AnalyticsApi>({
-  baseUrl: '/api/analytics',
-  manifest,
-  metrics: ['revenue', 'averageOrderValue'] as const,
-});
-
-function Dashboard() {
-  const revenue = useMetric('revenue', {
-    dimensions: ['country'],
-    filters: [{ field: 'status', operator: 'eq', value: 'completed' }],
-    orderBy: [{ field: 'revenue', direction: 'desc' }],
-    limit: 10,
-  });
+import type { AnalyticsApi } from '../server/api.js';
+import manifest from '../generated/hypequery-manifest.json';
 
-  const orders = useDataset('orders', {
-    dimensions: ['status'],
-    measures: ['revenue', 'orderCount'],
+export const { useMetric, useDataset } =
+  createAnalyticsHooks<AnalyticsApi>({
+    baseUrl: '/api/analytics',
+    manifest,
+    metrics: ['revenue'] as const,
   });
-
-  return (
-    <pre>
-      {JSON.stringify({ revenue: revenue.data, orders: orders.data }, null, 2)}
-    </pre>
-  );
-}
 ```
 
-## Pagination
-
-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.
+## Build the dashboard
 
 ```tsx
-function OrdersTable() {
-  const orders = useInfiniteDataset('orders', {
-    dimensions: ['status'],
-    measures: ['revenue'],
-    limit: 50,
+function RevenueByRegion() {
+  const revenue = useMetric('revenue', {
+    dimensions: ['region'],
+    orderBy: [{ field: 'revenue', direction: 'desc' }],
+    limit: 10,
   });
 
-  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>
-    </>
-  );
-}
-```
-
-`input.limit` is the page size; `input.offset`, if provided, is the starting offset.
-
-## Route Configuration
-
-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`.
-
-### Route manifest (recommended)
-
-`@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.
-
-```ts
-// server side (server-only module)
-export const manifest = api.manifest();
-
-// 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.
-
-#### Generating the manifest at build time
-
-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.
-
-```bash
-npx hypequery generate:manifest analytics/api.ts --output src/generated/hypequery-manifest.json
-```
+  if (revenue.isLoading) return <p>Loading revenue…</p>;
+  if (revenue.error) return <p>{revenue.error.message}</p>;
 
-```jsonc
-// package.json
-{
-  "scripts": {
-    "gen:manifest": "hypequery generate:manifest analytics/api.ts --output src/generated/hypequery-manifest.json",
-    "build": "npm run gen:manifest && <your client build>"
-  }
+  return <RevenueChart rows={revenue.data?.data ?? []} />;
 }
 ```
 
-```ts
-// client side — imports plain JSON, no server code in the bundle
-import { createAnalyticsHooks } from '@hypequery/react';
-import type { InferApiType } from '@hypequery/serve';
-import type { api } from '../analytics/api.js';
-import manifest from './generated/hypequery-manifest.json';
-
-type AnalyticsApi = InferApiType<typeof api>;
-
-const { useMetric, useDataset } = createAnalyticsHooks<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.
-
-> `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.
-
-### Explicit config
-
-If a manifest is not available at runtime, pass route config explicitly. This
-overrides any manifest entry.
-
-```ts
-const { useQuery } = createHooks<AnalyticsApi>({
-  baseUrl: '/api/analytics',
-  config: {
-    weeklyRevenue: { method: 'POST', path: '/weeklyRevenue' },
-  },
-});
-```
+Change the server contract and TypeScript points to the components that need updating.
 
-`path` may be relative to `baseUrl`, absolute within the same origin, or an absolute HTTP URL.
+## Included
 
-## Headers & auth
+- named query hooks and mutations;
+- metric and dataset hooks with selected-field inference;
+- infinite queries with semantic pagination metadata;
+- TanStack Query caching, retries, and refresh behavior;
+- static route manifests that keep server code out of browser bundles;
+- per-request auth headers and one-time `401` refresh.
 
-Pass static headers, or a function (sync or async) invoked per request — handy for
-attaching a fresh/short-lived token.
+## Why it matters
 
-```ts
-const hooks = createHooks<AnalyticsApi>({
-  baseUrl: '/api/analytics',
-  headers: async () => ({
-    authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
-
-Provide `onUnauthorized` to refresh credentials on a `401` and retry the request once
-with freshly resolved headers:
-
-```ts
-const hooks = createHooks<AnalyticsApi>({
-  baseUrl: '/api/analytics',
-  headers: () => ({ authorization: `Bearer ${tokenStore.access}` }),
-  onUnauthorized: async () => {
-    await tokenStore.refresh(); // throw to abort; resolve to retry once
-  },
-});
-```
-
-## Query Options
-
-TanStack Query options can be passed as the final argument.
-
-```tsx
-const result = useQuery(
-  'weeklyRevenue',
-  { startDate: '2026-01-01' },
-  {
-    staleTime: 60_000,
-    refetchOnWindowFocus: false,
-  },
-);
-```
-
-For no-input queries, use `queryOptions()` when an options object might look like input.
-
-```tsx
-import { queryOptions } from '@hypequery/react';
-
-const result = useQuery('health', queryOptions({
-  staleTime: 30_000,
-}));
-```
-
-## Mutations
-
-`useMutation(name)` uses the same endpoint typing and sends requests as `POST` by default unless route config overrides it.
-
-```tsx
-const refresh = useMutation('refreshReport');
-
-refresh.mutate({ reportId: 'revenue' });
-```
+The ClickHouse query, semantic metric, HTTP schema, and React component share one contract. That means fewer casts, fewer mismatched route types, and no frontend rewrite when a dashboard graduates from a prototype into a governed multi-tenant product surface.
 
-## Notes
+## Learn more
 
-- 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.
+- [React quick start](https://hypequery.com/docs/react/getting-started)
+- [Using queries](https://hypequery.com/docs/react/using-queries)
+- [Advanced patterns](https://hypequery.com/docs/react/advanced-patterns)
+- [Current capabilities](https://hypequery.com/docs/capabilities)
 
 ## License
 

package/dist/analyticsHooks.d.ts

@@ -4,7 +4,7 @@ import { HttpError } from './errors.js';
 import type { ExtractNames, QueryInput, QueryOutput, QueryOutputForInput } 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 QueryKey<Name extends string, Input> = Input extends never ? ['hypequery', string, Name] : ['hypequery', string, 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'>;
 /** Infinite-query options parameterized by the projected page type. */
 type InfiniteQueryOptions<Api, Key extends ExtractNames<Api>, TPage> = Omit<TanstackUseInfiniteQueryOptions<TPage, HttpError, InfiniteData<TPage, number>, QueryKey<Key, QueryInput<Api, Key>>, number>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'initialPageParam'>;
@@ -17,7 +17,7 @@ export interface CreateAnalyticsHooksConfig<Api extends Record<string, {
 export declare function createAnalyticsHooks<Api extends Record<string, {
     input: any;
     output: any;
-}>, TMetrics extends readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[] = readonly Exclude<ExtractNames<Api>, `dataset:${string}`>[]>(config: CreateAnalyticsHooksConfig<Api, TMetrics>): {
+}>, 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: QueryInput<Api, Name> extends never ? [name: Name, options?: QueryOptions<Api, Name>] : never): UseQueryResult<QueryOutput<Api, Name>, HttpError>;
         <Name extends TMetrics extends readonly (infer U)[] ? U extends string ? U : never : Exclude<ExtractNames<Api>, `dataset:${string}`>, const TInput extends QueryInput<Api, Name>>(name: Name, input: TInput, options?: QueryOptions<Api, Name>): UseQueryResult<QueryOutputForInput<Api, Name, TInput>, HttpError>;
@@ -28,9 +28,9 @@ export declare function createAnalyticsHooks<Api extends Record<string, {
     };
     readonly useInfiniteMetric: <Name extends TMetrics extends readonly (infer U)[] ? U extends string ? U : never : Exclude<ExtractNames<Api>, `dataset:${string}`>, const TInput extends QueryInput<Api, Name>>(name: Name, input: TInput, options?: InfiniteQueryOptions<Api, Name, QueryOutputForInput<Api, Name, TInput>>) => UseInfiniteQueryResult<InfiniteData<QueryOutputForInput<Api, Name, TInput>, number>, HttpError>;
     readonly useInfiniteDataset: <Name extends DatasetNamesFromApi<Api>, const TInput extends QueryInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>>>(name: Name, input: TInput, options?: InfiniteQueryOptions<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>, QueryOutputForInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>, TInput>>) => UseInfiniteQueryResult<InfiniteData<QueryOutputForInput<Api, Extract<ExtractNames<Api>, DatasetKey<Name>>, TInput>, number>, HttpError>;
-    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 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", string, Name] : ["hypequery", string, 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", string, Name] : ["hypequery", string, Name, QueryInput<Api, Name>]>, "queryKey" | "queryFn"> | undefined]) => UseQueryResult<QueryOutput<Api, Name>, HttpError>;
     readonly useMutation: <Name extends ExtractNames<Api>>(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 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"> | undefined) => UseInfiniteQueryResult<InfiniteData<QueryOutput<Api, Name>, number>, HttpError>;
+    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", string, Name] : ["hypequery", string, 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

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

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+export type ApiContract = Record<string, {
+    input: any;
+    output: any;
+}>;
+export interface QueryMethodConfig {
+    method?: string;
+    path?: string;
+}
+export interface RouteManifestEntry {
+    method?: string;
+    path?: string;
+}
+export type RouteManifest = Record<string, RouteManifestEntry>;
+type HeaderMap = Record<string, string | undefined>;
+export type HeadersInput = HeaderMap | (() => HeaderMap | Promise<HeaderMap>);
+export type TokenInput = string | (() => string | undefined | Promise<string | undefined>);
+export interface HypequeryClientConfig<Api extends ApiContract = ApiContract> {
+    baseUrl: string;
+    /**
+     * Stable cache scope for this deployment and authentication context. Omit it
+     * to create an isolated scope for this client instance.
+     */
+    cacheKey?: string;
+    fetchFn?: typeof fetch;
+    headers?: HeadersInput;
+    /** A bearer token or per-request token resolver. Never put a server API key in browser code. */
+    token?: TokenInput;
+    config?: Record<string, QueryMethodConfig>;
+    manifest?: RouteManifest;
+    /** Refresh authentication state after a 401. The request is retried once. */
+    onUnauthorized?: () => void | Promise<void>;
+    api?: Api;
+}
+export interface HypequeryClient<Api extends ApiContract = ApiContract> {
+    readonly config: Readonly<HypequeryClientConfig<Api>>;
+    readonly cacheKey: string;
+    request(name: string, input?: unknown, defaultMethod?: string, extraHeaders?: Record<string, string>): Promise<unknown>;
+}
+export declare function createHypequeryClient<Api extends ApiContract = ApiContract>(config: HypequeryClientConfig<Api>): HypequeryClient<Api>;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,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,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AAC9E,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE3F,MAAM,WAAW,qBAAqB,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,gGAAgG;IAChG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAqED,MAAM,WAAW,eAAe,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW;IACpE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzH;AAID,wBAAgB,qBAAqB,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW,EACzE,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC,GACjC,eAAe,CAAC,GAAG,CAAC,CAwFtB"}

package/dist/client.js

@@ -0,0 +1,128 @@
+import { HttpError } from './errors.js';
+const normalizeMethodConfig = (source) => {
+    if (!source)
+        return {};
+    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 {};
+    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) {
+        return normalizeMethodConfig(api._routeConfig);
+    }
+    if ('queries' in api &&
+        typeof api.queries === 'object' &&
+        api.queries !== null) {
+        return normalizeMethodConfig(api.queries);
+    }
+    return {};
+};
+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 `${ensureTrailingSlash(baseUrl)}${name}`;
+};
+const parseResponse = async (response) => {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+const resolveHeaders = async (headers) => {
+    if (!headers)
+        return {};
+    const raw = typeof headers === 'function' ? await headers() : headers;
+    return Object.fromEntries(Object.entries(raw).filter(([, value]) => value !== undefined));
+};
+const resolveToken = async (token) => typeof token === 'function' ? token() : token;
+let clientSequence = 0;
+export function createHypequeryClient(config) {
+    const { baseUrl, fetchFn = fetch, headers, token, config: explicitConfig = {}, manifest, onUnauthorized, api, } = config;
+    const cacheKey = config.cacheKey ?? `client:${++clientSequence}`;
+    const finalConfig = {
+        ...deriveMethodConfig(api),
+        ...(manifest ? normalizeMethodConfig(manifest) : {}),
+        ...explicitConfig,
+    };
+    const request = async (name, input, defaultMethod = 'GET', extraHeaders) => {
+        const methodConfig = finalConfig[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 createHypequeryClient().`);
+        }
+        const url = buildUrl(baseUrl, name, methodConfig?.path);
+        const method = methodConfig?.method ?? defaultMethod;
+        let finalUrl = url;
+        let body;
+        if (method === 'GET' && input && typeof input === 'object') {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(input)) {
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value))
+                    value.forEach((item) => params.append(key, String(item)));
+                else
+                    params.append(key, String(value));
+            }
+            const queryString = params.toString();
+            finalUrl = queryString ? `${url}?${queryString}` : url;
+        }
+        else if (input !== undefined) {
+            body = JSON.stringify(input);
+        }
+        const attempt = async () => {
+            const [resolvedHeaders, resolvedToken] = await Promise.all([
+                resolveHeaders(headers),
+                resolveToken(token),
+            ]);
+            return fetchFn(finalUrl, {
+                method,
+                headers: {
+                    ...resolvedHeaders,
+                    ...(resolvedToken ? { authorization: `Bearer ${resolvedToken}` } : {}),
+                    ...(extraHeaders ?? {}),
+                    ...(body ? { 'content-type': 'application/json' } : {}),
+                },
+                body,
+            });
+        };
+        let response = await attempt();
+        if (response.status === 401 && onUnauthorized) {
+            await onUnauthorized();
+            response = await attempt();
+        }
+        if (!response.ok) {
+            const errorBody = await parseResponse(response);
+            throw new HttpError(`${method} request to ${finalUrl} failed with status ${response.status}`, response.status, errorBody);
+        }
+        return response.json();
+    };
+    return Object.freeze({
+        cacheKey,
+        config: Object.freeze({ ...config }),
+        request,
+    });
+}

package/dist/createHooks.d.ts

@@ -1,60 +1,16 @@
 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 | 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;
-}
+import { type ApiContract, type HypequeryClientConfig } from './client.js';
+export type CreateHooksConfig<TApi extends ApiContract = ApiContract> = HypequeryClientConfig<TApi>;
 declare const OPTIONS_SYMBOL: unique symbol;
 export declare function queryOptions<T extends object>(opts: T): T & {
     [OPTIONS_SYMBOL]: true;
 };
-export declare function createHooks<Api extends Record<string, {
-    input: any;
-    output: any;
-}>>(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>;
+export declare function createHooks<Api extends ApiContract>(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", string, Name] : ["hypequery", string, 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", string, Name] : ["hypequery", string, 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>;
+    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", string, Name] : ["hypequery", string, 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,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"}
+{"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;AACxC,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAWrB,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,WAAW,GAAG,WAAW,IAClE,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAE9B,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;AAcD,wBAAgB,WAAW,CAAC,GAAG,SAAS,WAAW,EACjD,MAAM,CAAC,EAAE,iBAAiB,CAAC,GAAG,CAAC;wBA0Bb,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,+mBAE7C,cAAc,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC;2BAyC/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;gCAyBpD,IAAI,SAAS,YAAY,CAAC,GAAG,CAAC,QAChD,IAAI,SACH,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,yUAE3B,sBAAsB,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,SAAS,CAAC;EA6BnF"}

package/dist/createHooks.js

@@ -1,69 +1,10 @@
 import { useQuery as useTanstackQuery, useMutation as useTanstackMutation, useInfiniteQuery as useTanstackInfiniteQuery, } from '@tanstack/react-query';
-import { HttpError } from './errors.js';
+import { createHypequeryClient, } from './client.js';
+import { useOptionalHypequeryClient } from './provider.js';
 const OPTIONS_SYMBOL = Symbol.for('hypequery-options');
 export function queryOptions(opts) {
     return { ...opts, [OPTIONS_SYMBOL]: true };
 }
-const normalizeMethodConfig = (source) => {
-    if (!source)
-        return {};
-    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) {
-        return normalizeMethodConfig(api._routeConfig);
-    }
-    if ('queries' in api &&
-        typeof api.queries === 'object' &&
-        api.queries !== null) {
-        return normalizeMethodConfig(api.queries);
-    }
-    return {};
-};
-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 `${ensureTrailingSlash(baseUrl)}${name}`;
-};
-const parseResponse = async (res) => {
-    const text = await res.text();
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-};
 const isOptionsBag = (value) => {
     return Boolean(value && typeof value === 'object' && OPTIONS_SYMBOL in value);
 };
@@ -76,76 +17,18 @@ const looksLikeQueryOptions = (value) => {
     const matches = optionKeys.filter((key) => key in value).length;
     return matches >= 2;
 };
-const resolveHeaders = async (headers) => {
-    if (!headers)
-        return {};
-    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 = {}, 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 configuredClient = config ? createHypequeryClient(config) : null;
+    function useResolvedClient() {
+        const providerClient = useOptionalHypequeryClient();
+        const client = configuredClient ?? providerClient;
+        if (!client) {
+            throw new Error('Configure createHooks() directly or render inside <HypequeryProvider>.');
         }
-        const url = buildUrl(baseUrl, name, methodConfig?.path);
-        const method = methodConfig?.method ?? defaultMethod;
-        let finalUrl = url;
-        let body;
-        if (method === 'GET' && input && typeof input === 'object') {
-            const params = new URLSearchParams();
-            for (const [key, value] of Object.entries(input)) {
-                if (value === undefined || value === null)
-                    continue;
-                if (Array.isArray(value)) {
-                    value.forEach((item) => params.append(key, String(item)));
-                }
-                else {
-                    params.append(key, String(value));
-                }
-            }
-            const queryString = params.toString();
-            finalUrl = queryString ? `${url}?${queryString}` : url;
-        }
-        else if (input !== undefined) {
-            body = JSON.stringify(input);
-        }
-        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);
-        }
-        return res.json();
-    };
+        return client;
+    }
     function useQuery(...args) {
+        const client = useResolvedClient();
         const [name, potentialInputOrOptions, maybeOptions] = args;
         let input;
         let options;
@@ -163,19 +46,20 @@ export function createHooks(config) {
         }
         const queryKey = (() => {
             if (input === undefined) {
-                return ['hypequery', name];
+                return ['hypequery', client.cacheKey, name];
             }
-            return ['hypequery', name, input];
+            return ['hypequery', client.cacheKey, name, input];
         })();
         return useTanstackQuery({
             queryKey,
-            queryFn: () => fetchQuery(name, input),
+            queryFn: () => client.request(name, input),
             ...(options ?? {}),
         });
     }
     function useMutation(name, options) {
+        const client = useResolvedClient();
         return useTanstackMutation({
-            mutationFn: (input) => fetchQuery(name, input, 'POST'),
+            mutationFn: (input) => client.request(name, input, 'POST'),
             ...options,
         });
     }
@@ -186,12 +70,13 @@ export function createHooks(config) {
      * provided, is the starting offset.
      */
     function useInfiniteQuery(name, input, options) {
+        const client = useResolvedClient();
         const initialOffset = input?.offset ?? 0;
-        const queryKey = ['hypequery', name, input];
+        const queryKey = ['hypequery', client.cacheKey, name, input];
         return useTanstackInfiniteQuery({
             queryKey,
             initialPageParam: initialOffset,
-            queryFn: ({ pageParam }) => fetchQuery(name, { ...input, offset: pageParam }, 'POST', { 'x-include-meta': 'true' }),
+            queryFn: ({ pageParam }) => client.request(name, { ...input, offset: pageParam }, 'POST', { 'x-include-meta': 'true' }),
             getNextPageParam: (lastPage) => {
                 const pagination = lastPage.meta?.pagination;
                 if (!pagination || !pagination.hasMore)

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 export { createHooks, queryOptions } from './createHooks.js';
 export { createAnalyticsHooks } from './analyticsHooks.js';
+export { createHypequeryClient } from './client.js';
+export { HypequeryProvider, useHypequeryClient } from './provider.js';
 export { HttpError } from './errors.js';
 export type { QueryInput, QueryOutput, HttpMethod } from './types.js';
-export type { CreateHooksConfig, QueryMethodConfig } from './createHooks.js';
+export type { CreateHooksConfig } from './createHooks.js';
+export type { ApiContract, HeadersInput, HypequeryClient, HypequeryClientConfig, QueryMethodConfig, RouteManifest, RouteManifestEntry, TokenInput, } from './client.js';
+export type { HypequeryProviderProps } from './provider.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,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"}
+{"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,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { createHooks, queryOptions } from './createHooks.js';
 export { createAnalyticsHooks } from './analyticsHooks.js';
+export { createHypequeryClient } from './client.js';
+export { HypequeryProvider, useHypequeryClient } from './provider.js';
 export { HttpError } from './errors.js';

package/dist/provider.d.ts

@@ -0,0 +1,13 @@
+import { QueryClient } from '@tanstack/react-query';
+import { type ReactNode } from 'react';
+import type { ApiContract, HypequeryClient } from './client.js';
+export interface HypequeryProviderProps<Api extends ApiContract = ApiContract> {
+    client: HypequeryClient<Api>;
+    children: ReactNode;
+    /** Reuse an application's existing TanStack Query client when supplied. */
+    queryClient?: QueryClient;
+}
+export declare function HypequeryProvider<Api extends ApiContract>({ client, children, queryClient, }: HypequeryProviderProps<Api>): import("react/jsx-runtime").JSX.Element;
+export declare function useHypequeryClient<Api extends ApiContract = ApiContract>(): HypequeryClient<Api>;
+export declare function useOptionalHypequeryClient<Api extends ApiContract = ApiContract>(): HypequeryClient<Api> | null;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAuB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAIhE,MAAM,WAAW,sBAAsB,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW;IAC3E,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAAC,GAAG,SAAS,WAAW,EAAE,EACzD,MAAM,EACN,QAAQ,EACR,WAAW,GACZ,EAAE,sBAAsB,CAAC,GAAG,CAAC,2CAS7B;AAED,wBAAgB,kBAAkB,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW,0BAMvE;AAED,wBAAgB,0BAA0B,CAAC,GAAG,SAAS,WAAW,GAAG,WAAW,KACvC,eAAe,CAAC,GAAG,CAAC,GAAG,IAAI,CACnE"}

package/dist/provider.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { createContext, useContext, useState } from 'react';
+const HypequeryContext = createContext(null);
+export function HypequeryProvider({ client, children, queryClient, }) {
+    const [defaultQueryClient] = useState(() => new QueryClient());
+    return (_jsx(HypequeryContext.Provider, { value: client, children: _jsx(QueryClientProvider, { client: queryClient ?? defaultQueryClient, children: children }) }));
+}
+export function useHypequeryClient() {
+    const client = useOptionalHypequeryClient();
+    if (!client) {
+        throw new Error('Hypequery hooks must be rendered inside <HypequeryProvider>.');
+    }
+    return client;
+}
+export function useOptionalHypequeryClient() {
+    return useContext(HypequeryContext);
+}

package/dist/provider.test.d.ts

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

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

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

package/dist/provider.test.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient } from '@tanstack/react-query';
+import { describe, expect, it, vi } from 'vitest';
+import { createHypequeryClient } from './client.js';
+import { createHooks } from './createHooks.js';
+import { HypequeryProvider } from './provider.js';
+function success(data) {
+    return { ok: true, status: 200, json: async () => data };
+}
+describe('HypequeryProvider', () => {
+    it('configures generated hooks once and supplies their TanStack Query client', async () => {
+        const fetchFn = vi.fn().mockResolvedValue(success({ message: 'Hello Luke' }));
+        const client = createHypequeryClient({
+            baseUrl: 'https://acme.hypequery.cloud/v1/analytics/production',
+            token: async () => 'browser-token',
+            fetchFn: fetchFn,
+            manifest: { greeting: { method: 'GET', path: 'queries/greeting' } },
+        });
+        const { useQuery } = createHooks();
+        const wrapper = ({ children }) => (_jsx(HypequeryProvider, { client: client, children: children }));
+        const { result } = renderHook(() => useQuery('greeting', { name: 'Luke' }), { wrapper });
+        await waitFor(() => expect(result.current.data).toEqual({ message: 'Hello Luke' }));
+        expect(fetchFn).toHaveBeenCalledWith('https://acme.hypequery.cloud/v1/analytics/production/queries/greeting?name=Luke', expect.objectContaining({
+            headers: expect.objectContaining({ authorization: 'Bearer browser-token' }),
+        }));
+    });
+    it('isolates cached responses when the provider client changes', async () => {
+        const firstFetch = vi.fn().mockResolvedValue(success({ message: 'First user' }));
+        const secondFetch = vi.fn().mockResolvedValue(success({ message: 'Second user' }));
+        const createClient = (fetchFn) => createHypequeryClient({
+            baseUrl: 'https://acme.hypequery.cloud/v1/analytics/production',
+            fetchFn: fetchFn,
+            manifest: { greeting: { method: 'GET', path: 'queries/greeting' } },
+        });
+        const firstClient = createClient(firstFetch);
+        const secondClient = createClient(secondFetch);
+        const queryClient = new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+        });
+        const { useQuery } = createHooks();
+        let activeClient = firstClient;
+        const wrapper = ({ children }) => (_jsx(HypequeryProvider, { client: activeClient, queryClient: queryClient, children: children }));
+        const view = renderHook(() => useQuery('greeting', { name: 'Luke' }), { wrapper });
+        await waitFor(() => expect(view.result.current.data).toEqual({ message: 'First user' }));
+        activeClient = secondClient;
+        view.rerender();
+        await waitFor(() => expect(view.result.current.data).toEqual({ message: 'Second user' }));
+        expect(firstClient.cacheKey).not.toBe(secondClient.cacheKey);
+        expect(firstFetch).toHaveBeenCalledTimes(1);
+        expect(secondFetch).toHaveBeenCalledTimes(1);
+    });
+});

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@hypequery/react",
-  "version": "0.5.0",
-  "description": "React hooks for consuming hypequery APIs",
+  "version": "0.6.0",
+  "description": "Type-safe React and TanStack Query hooks for ClickHouse analytics, metrics, and datasets",
+  "keywords": [
+    "react",
+    "tanstack-query",
+    "clickhouse",
+    "analytics",
+    "semantic-layer",
+    "typescript",
+    "query-builder",
+    "orm",
+    "dashboard",
+    "embedded-analytics"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -30,8 +42,17 @@
     "react-dom": "^18.2.0",
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
-    "@hypequery/datasets": "0.8.0",
-    "@hypequery/serve": "0.8.0"
+    "@hypequery/serve": "0.15.3",
+    "@hypequery/datasets": "0.13.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hypequery/hypequery.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://hypequery.com",
+  "bugs": {
+    "url": "https://github.com/hypequery/hypequery/issues"
   },
   "publishConfig": {
     "access": "public"