@shipworthy/openapi-react-query 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipworthy AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,459 @@
-# Temporary Holding Version
+# @shipworthy/openapi-react-query
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed [TanStack Query](https://tanstack.com/query) hooks for React, driven by the `paths` type
+generated from an OpenAPI document. You pass your generated `paths` interface once, then call
+hooks with a URL path such as `"/pets/{pet_id}"`. TypeScript infers the request parameters,
+request body, response data, and error body for that operation. No per-operation code is
+generated. Requests go through
+[`@shipworthy/openapi-fetch`](../openapi-fetch), which this package installs for you. You
+generate the `paths` type with `openapi generate typescript` from `@shipworthy/openapi-cli` and
+`@shipworthy/openapi-typescript`.
+
+Use this package when you want path-based hooks with a ready-made provider. Use the sibling
+`@shipworthy/openapi-tanstack-query` instead when you want generated, operation-ID-based query
+utilities that work with TanStack's own `useQuery`.
+
+## Installation
+
+```sh
+bun add @shipworthy/openapi-react-query @tanstack/react-query react
+```
+
+To generate types, also install the CLI, the TypeScript generator, and the generator's peers as dev dependencies:
+
+```sh
+bun add -d @shipworthy/openapi-cli @shipworthy/openapi-typescript effect@^4
+```
+
+| Requirement                  | Value                                                                                                                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Peer `@tanstack/react-query` | `^5.104.1`                                                                                                                        |
+| Peer `react`                 | `^18.0.0 \|\| ^19.0.0`                                                                                                            |
+| Dependency                   | `@shipworthy/openapi-fetch` (installed automatically)                                                                             |
+| Module format                | ESM only (`"type": "module"`). There is no CommonJS build.                                                                        |
+| Shipped files                | Compiled JavaScript and `.d.ts` declarations in `dist/` (`exports["."]` and the `react-native` field point to `./dist/index.js`). |
+| CLI runtime                  | The `openapi` binary runs on Node.js `>=22.19.0` or Bun (`bunx --bun @shipworthy/openapi-cli`)                                    |
+
+No TypeScript or TSX transpilation of `node_modules` is needed. The provider's JSX is compiled
+with the automatic runtime (`react/jsx-runtime`), so there is no `import React`. The package
+declares no Node.js `engines` range. It uses the Fetch API globals supplied by your browser,
+React Native environment, or server runtime. The Node.js requirement above applies to code generation.
+
+## Quick start
+
+### 1. Generate the `paths` type
+
+```sh
+bunx --bun @shipworthy/openapi-cli generate typescript ./openapi.yaml -o ./src/generated/api.ts
+```
+
+The input can be a local JSON or YAML file or a URL. If you omit the input, the CLI reads the
+schema from stdin. If you omit `-o`, it writes to stdout. The output exports `interface paths`,
+along with `components`, `operations`, and related types.
+
+### 2. Wrap your app in `ApiClientProvider`
+
+```tsx
+import { ApiClientProvider } from "@shipworthy/openapi-react-query";
+
+export function Root() {
+  return (
+    <ApiClientProvider baseUrl="https://api.example.com">
+      <PetList />
+    </ApiClientProvider>
+  );
+}
+```
+
+`ApiClientProvider` also renders a TanStack `QueryClientProvider`, so you don't need a second
+provider.
+
+### 3. Bind your `paths` type and call the hooks
+
+```tsx
+import { useApiClientQuery } from "@shipworthy/openapi-react-query";
+import type { paths } from "./generated/api";
+
+function PetList() {
+  const useQuery = useApiClientQuery<paths>(); // bind the schema once
+  const { data, error, isPending } = useQuery("/pets", {
+    params: { query: { limit: 20 } },
+  });
+
+  if (isPending) return <p>Loading…</p>;
+  if (error) return <p>{error.title}</p>; // typed from the operation's error response
+  return (
+    <ul>
+      {data.data.map((pet) => (
+        <li key={pet.id}>{pet.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+The examples below use this `paths` shape, abbreviated from `openapi-typescript` output:
+
+```ts
+interface Pet {
+  id: string;
+  name: string;
+}
+interface Problem {
+  title: string;
+}
+
+export interface paths {
+  "/pets": {
+    get: {
+      parameters: { query?: { limit?: number; cursor?: number } };
+      responses: {
+        200: { content: { "application/json": { data: Pet[]; next_cursor?: number } } };
+        400: { content: { "application/json": Problem } };
+      };
+    };
+    post: {
+      requestBody: { content: { "application/json": { name: string } } };
+      responses: {
+        201: { content: { "application/json": Pet } };
+        422: { content: { "application/json": Problem } };
+      };
+    };
+  };
+  "/pets/{pet_id}": {
+    get: {
+      parameters: { path: { pet_id: string } };
+      responses: {
+        200: { content: { "application/json": Pet } };
+        404: { content: { "application/json": Problem } };
+      };
+    };
+    delete: {
+      parameters: { path: { pet_id: string } };
+      responses: { 204: { content?: never } };
+    };
+  };
+}
+```
+
+## API
+
+The package has a single entry point: `@shipworthy/openapi-react-query`.
+
+| Export                      | Kind                       |
+| --------------------------- | -------------------------- |
+| `ApiClientProvider`         | React component            |
+| `useApiClient`              | Hook                       |
+| `useApiClientQuery`         | Hook factory               |
+| `useApiClientSuspenseQuery` | Hook factory               |
+| `useApiClientQueryOptions`  | Hook factory               |
+| `useApiClientInfiniteQuery` | Hook factory               |
+| `useApiClientMutation`      | Hook factory               |
+| `createApiClient`           | Function (no React needed) |
+| `ApiClient`                 | Type                       |
+| `QueryKey`                  | Type                       |
+
+### Calling the hook factories
+
+Each `useApiClient*` export takes your `paths` type as a type argument and returns a hook
+function:
+
+```ts
+const useQuery = useApiClientQuery<paths>();
+```
+
+Calling the factory runs no hooks. It returns the same function every time. The returned
+function is a React hook: it reads the provider context and calls TanStack, so it must follow
+the Rules of Hooks. If you don't pass `paths`, it defaults to `{}`, and no path type-checks.
+
+The returned hooks take arguments in this order:
+
+```
+hook(path, [method], init, options, queryClient)
+```
+
+| Argument      | Description                                                                                                                                                                                                                                                                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`        | A key of `paths`, such as `"/pets/{pet_id}"`. Only paths that have the selected method are accepted.                                                                                                                                                                                                                                                                  |
+| `method`      | Optional lowercase HTTP method: `"get" \| "put" \| "post" \| "delete" \| "options" \| "head" \| "patch" \| "trace"`. Query hooks default to `"get"`; the mutation hook defaults to `"post"`. The hook treats a string second argument as the method.                                                                                                                  |
+| `init`        | `openapi-fetch` request options: `params.path`, `params.query`, `params.header`, `params.cookie`, `body`, and similar. It is required when the operation has required parameters or a required body; otherwise it is optional. You can pass extra keys, which go to `openapi-fetch` unchanged. The mutation hook takes no `init` here; pass it to `mutate()` instead. |
+| `options`     | TanStack options for the underlying hook, minus `queryKey`/`queryFn` (or `mutationKey`/`mutationFn`). `select` is typed, and the result's `data` type follows its return type.                                                                                                                                                                                        |
+| `queryClient` | Optional `QueryClient`. It is passed through to TanStack, and overrides the one from context.                                                                                                                                                                                                                                                                         |
+
+How results behave:
+
+- **`data`** is the operation's success response body (the 2XX JSON).
+- **`error`** is the parsed error response body (the non-2XX JSON) that `openapi-fetch` returns.
+  The hooks throw this body itself, not an `Error` instance. Network failures from `fetch`
+  propagate as they are.
+- **Empty responses:** in the query and suspense hooks, a `204` response or a response with
+  `Content-Length: 0` resolves to `null` instead of `undefined`.
+- **Cancellation:** query hooks pass TanStack's `AbortSignal` to the request as `signal`.
+
+### `ApiClientProvider`
+
+```ts
+function ApiClientProvider(props: {
+  baseUrl: string;
+  queryClient?: QueryClient;
+  children?: React.ReactNode;
+}): JSX.Element;
+```
+
+The provider creates an `openapi-fetch` client for `baseUrl` and puts it in context. It also
+renders `QueryClientProvider`.
+
+If you don't pass `queryClient`, the provider uses a default `QueryClient` with
+`defaultOptions.queries.staleTime = 60_000`. In the browser, one module-level instance is
+created and reused. On the server (TanStack's `isServer`), it creates a new instance on every
+render.
+
+The provider takes no headers or auth token. See [Limitations](#limitations-and-caveats).
+
+```tsx
+import { QueryClient } from "@tanstack/react-query";
+import { ApiClientProvider } from "@shipworthy/openapi-react-query";
+
+const queryClient = new QueryClient();
+
+<ApiClientProvider baseUrl={import.meta.env.VITE_API_URL} queryClient={queryClient}>
+  <App />
+</ApiClientProvider>;
+```
+
+### `useApiClient<Paths>()`
+
+```ts
+function useApiClient<Paths extends {} = {}>(): Client<Paths>; // Client from @shipworthy/openapi-fetch
+```
+
+Returns the provider's `openapi-fetch` client, with methods `GET`, `POST`, `PUT`, `PATCH`,
+`DELETE`, and so on. Use it for one-off imperative calls inside components.
+
+If no `ApiClientProvider` is above the component, it throws
+`Error("useApiClient must be used within ApiClientProvider")`. Every hook in this package
+calls `useApiClient`, so they all throw this error outside the provider.
+
+```ts
+const client = useApiClient<paths>();
+const { data, error, response } = await client.GET("/pets/{pet_id}", {
+  params: { path: { pet_id: "p1" } },
+});
+```
+
+### `useApiClientQuery<Paths>()`
+
+Returns a hook that wraps TanStack `useQuery` and returns `UseQueryResult<TData, TError>`.
+
+```ts
+const useQuery = useApiClientQuery<paths>();
+
+// Path params are required, so the call needs init.
+const pet = useQuery(
+  "/pets/{pet_id}",
+  { params: { path: { pet_id: "p1" } } },
+  { staleTime: 5_000 },
+);
+
+// init is optional here, so pass undefined to reach options. select narrows the data type to string[].
+const names = useQuery("/pets", undefined, { select: (res) => res.data.map((p) => p.name) });
+
+// Explicit method
+const same = useQuery("/pets/{pet_id}", "get", { params: { path: { pet_id: "p1" } } });
+```
+
+The query key is `[method, path]`, or `[method, path, init]` when you pass `init`. For example:
+`["get", "/pets", { params: { query: { limit: 20 } } }]`.
+
+### `useApiClientSuspenseQuery<Paths>()`
+
+Same arguments as `useApiClientQuery`. It wraps TanStack `useSuspenseQuery`, so `data` is always
+defined. Render the component inside a `<Suspense>` boundary, and catch errors with an error
+boundary.
+
+```tsx
+function PetDetail({ id }: { id: string }) {
+  const useSuspenseQuery = useApiClientSuspenseQuery<paths>();
+  const { data } = useSuspenseQuery("/pets/{pet_id}", { params: { path: { pet_id: id } } });
+  return <h1>{data.name}</h1>;
+}
+```
+
+### `useApiClientQueryOptions<Paths>()`
+
+Returns a hook that builds a TanStack options object (`{ queryKey, queryFn, ...options }`)
+instead of running a query. It takes the same `path`, `[method]`, `init`, and `options`
+arguments, but no `queryClient`. The returned `queryFn` is never `skipToken`.
+
+Use the result with TanStack APIs: `useQuery`, `useQueries`, `queryClient.prefetchQuery`,
+`fetchQuery`, `ensureQueryData`, and so on. It reads the client from context, so you must call
+it inside a component under `ApiClientProvider`.
+
+```tsx
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+
+const queryOptions = useApiClientQueryOptions<paths>();
+const options = queryOptions("/pets", { params: { query: { limit: 20 } } });
+
+const result = useQuery(options); // result.data is typed
+const queryClient = useQueryClient();
+void queryClient.prefetchQuery(options);
+```
+
+### `useApiClientInfiniteQuery<Paths>()`
+
+Wraps TanStack `useInfiniteQuery` for cursor- or offset-paginated endpoints. Its arguments
+differ from the other query hooks: `init` and `options` are required.
+
+```
+hook(path, [method], init, options, queryClient?)
+```
+
+- `options` takes TanStack's infinite-query options, so `initialPageParam` and
+  `getNextPageParam` are required. It also takes `pageParamName?: string` (default
+  `"cursor"`).
+- On each page request, the hook sets `params.query[pageParamName]` to the current page
+  param, merged with any query params in `init`. If the page param is `undefined`, the hook
+  sends `0`.
+- `data` is TanStack's `InfiniteData<TData>`, an object with `pages` and `pageParams`.
+- The query key is the same as for `useApiClientQuery`. It does not include the page param.
+- Unlike the other query hooks, it applies no `204` → `null` handling.
+
+```ts
+const useInfiniteQuery = useApiClientInfiniteQuery<paths>();
+const { data, fetchNextPage, hasNextPage } = useInfiniteQuery(
+  "/pets",
+  { params: { query: { limit: 20 } } },
+  {
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.next_cursor, // undefined ends pagination
+    pageParamName: "cursor", // sent as ?cursor=<pageParam>
+  },
+);
+const pets = data?.pages.flatMap((page) => page.data);
+```
+
+### `useApiClientMutation<Paths>()`
+
+Wraps TanStack `useMutation` and returns `UseMutationResult<TData, TError, TInit>`.
+
+```
+hook(path, [method], options?, queryClient?)
+```
+
+- The method defaults to `"post"`.
+- You pass the request `init` (body, params) to `mutate()` or `mutateAsync()`, not to the hook.
+- The mutation key is `[method, path]`.
+- Options are TanStack mutation options minus `mutationKey` and `mutationFn`.
+
+```ts
+import { useQueryClient } from "@tanstack/react-query";
+
+const useMutation = useApiClientMutation<paths>();
+const queryClient = useQueryClient();
+
+const createPet = useMutation("/pets", {
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["get", "/pets"] }),
+});
+createPet.mutate({ body: { name: "Rex" } });
+
+const deletePet = useMutation("/pets/{pet_id}", "delete");
+deletePet.mutate({ params: { path: { pet_id: "p1" } } });
+```
+
+### `createApiClient<Paths>(baseUrl, authToken?)`
+
+```ts
+function createApiClient<Paths extends {}>(baseUrl: string, authToken?: string): Client<Paths>;
+```
+
+Creates a standalone `openapi-fetch` client. Use it outside React, for example in scripts,
+server code, or loaders.
+
+- If you pass `authToken`, every request sends `Authorization: Bearer <authToken>`.
+- Methods return `{ data, error, response }` and do not throw on HTTP errors.
+
+This client is separate from the one `ApiClientProvider` creates, and the hooks don't use it.
+
+```ts
+import { createApiClient } from "@shipworthy/openapi-react-query";
+import type { paths } from "./generated/api";
+
+const api = createApiClient<paths>("https://api.example.com", process.env.API_TOKEN);
+const { data, error, response } = await api.GET("/pets", { params: { query: { limit: 10 } } });
+if (error) console.error(response.status, error.title);
+```
+
+### Types
+
+- **`ApiClient`**: `ReturnType<typeof createApiClient>`, the client type with its `Paths`
+  parameter erased. For a client bound to your schema, annotate with
+  `ReturnType<typeof createApiClient<paths>>`.
+- **`QueryKey<Paths, Method, Path, Init?>`**: the key that the query hooks build.
+  - It is `readonly [Method, Path]` when `Init` is `undefined`.
+  - Otherwise it is `readonly [Method, Path, Init]`.
+
+  ```ts
+  import type { QueryKey } from "@shipworthy/openapi-react-query";
+  type PetsKey = QueryKey<paths, "get", "/pets">;
+  const key: PetsKey = ["get", "/pets", { params: { query: { limit: 20 } } }];
+  ```
+
+## Cache keys and invalidation
+
+| Hook                                                                                                                | Key                                        |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| Queries (`useApiClientQuery`, `useApiClientSuspenseQuery`, `useApiClientQueryOptions`, `useApiClientInfiniteQuery`) | `[method, path]` or `[method, path, init]` |
+| Mutations                                                                                                           | `[method, path]`                           |
+
+The method is lowercase, and the path is the OpenAPI template (`"/pets/{pet_id}"`), not the
+expanded URL. TanStack matches keys by prefix, so
+`queryClient.invalidateQueries({ queryKey: ["get", "/pets"] })` invalidates every `GET /pets`
+query, whatever its `init`.
+
+## Limitations and caveats
+
+- **No auth or headers from the provider.** `ApiClientProvider` accepts only `baseUrl` and
+  `queryClient`. To send headers, pass them per request in `init` (`params.header`, or extra
+  `openapi-fetch` options). `createApiClient`'s `authToken` affects only that standalone client.
+- **The provider creates a new client on every render** of `ApiClientProvider`. Place it high
+  in the tree, where it rarely re-renders.
+- **Thrown errors are response bodies,** not `Error` objects, so `error instanceof Error` is
+  `false` for HTTP errors.
+- **OpenAPI support** depends on `@shipworthy/openapi-typescript`, which generates the `paths`
+  type. That package describes itself as converting OpenAPI 3.0 and 3.1 schemas.
+
+## Troubleshooting
+
+| Symptom                                              | Cause / fix                                                                                              |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `useApiClient must be used within ApiClientProvider` | A hook was called outside `ApiClientProvider`. Wrap the tree.                                            |
+| Every path is a type error                           | You called the factory without `paths` (`useApiClientQuery()`). Use `useApiClientQuery<paths>()`.        |
+| A path is not accepted                               | That path has no operation for the method. Pass the method explicitly, e.g. `useQuery("/x", "post", …)`. |
+| Argument-count error when you omit `init`            | The operation has required path, query, or header params, or a required body, so `init` is required.     |
+| Infinite query never sends a page                    | The API expects a query param other than `cursor`. Set `pageParamName`.                                  |
+
+## Key facts (for AI agents)
+
+- Import everything from `@shipworthy/openapi-react-query`. There are no subpath exports and
+  no CLI in this package.
+- Generate the `paths` type with
+  `openapi generate typescript <schema> -o <file>.ts` (`@shipworthy/openapi-cli` +
+  `@shipworthy/openapi-typescript`). Import it as `import type { paths } from "<file>"`.
+- Mount `<ApiClientProvider baseUrl="…">` once. It already includes `QueryClientProvider`.
+- The hook factories are curried. Call `useApiClientQuery<paths>()` first, and then call the
+  returned hook as `hook(path, method?, init, options?, queryClient?)`. Never call
+  `useApiClientQuery<paths>("/path", …)`.
+- Methods are lowercase strings. Queries default to `"get"`; mutations default to `"post"`.
+- Mutation `init` goes to `mutate(init)`, not to the hook.
+- Infinite queries need `initialPageParam` and `getNextPageParam`. The page param is sent as
+  the `pageParamName` query param (default `cursor`).
+- Query keys are `[method, path, init?]`; mutation keys are `[method, path]`.
+- Hooks throw the typed error body. Query and suspense hooks resolve empty `204` responses as
+  `null`.
+- `createApiClient(baseUrl, authToken?)` is for non-React use. The hooks don't use it.
+- Peers: `react` `^18 || ^19`, `@tanstack/react-query` `^5.104.1`. ESM-only compiled JavaScript with `.d.ts` declarations.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export declare function createApiClient<Paths extends {}>(baseUrl: string, authToken?: string): import("@shipworthy/openapi-fetch").Client<Paths, `${string}/${string}`>;
+export type ApiClient = ReturnType<typeof createApiClient>;

package/dist/client.js

@@ -0,0 +1,7 @@
+import createClient from "@shipworthy/openapi-fetch";
+export function createApiClient(baseUrl, authToken) {
+    return createClient({
+        baseUrl,
+        headers: authToken ? { Authorization: `Bearer ${authToken}` } : undefined,
+    });
+}

package/dist/hooks/use-infinite-query.d.ts

@@ -0,0 +1,13 @@
+import { type InfiniteData, type QueryClient, type UseInfiniteQueryOptions, type UseInfiniteQueryResult } from "@tanstack/react-query";
+import type { FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod } from "@shipworthy/openapi-fetch";
+import { type InferSelectReturnType, type InitWithUnknowns, type QueryKey } from "../utils.ts";
+interface ApiClientInfiniteQuery<Paths extends Record<string, any>> {
+    <Path extends PathsWithMethod<Paths, "get">, Init extends MaybeOptionalInit<Paths[Path], "get">, Response extends Required<FetchResponse<Paths[Path]["get"], Init, MediaType>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], Response["error"], InferSelectReturnType<InfiniteData<Response["data"]>, Options["select"]>, QueryKey<Paths, "get", Path>, unknown>, "queryKey" | "queryFn"> & {
+        pageParamName?: string;
+    }>(path: Path, init: InitWithUnknowns<Init>, options: Options, queryClient?: QueryClient): UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"]>, Options["select"]>, Response["error"]>;
+    <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method] & Record<string | number, any>, Init, MediaType>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], Response["error"], InferSelectReturnType<InfiniteData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>, unknown>, "queryKey" | "queryFn"> & {
+        pageParamName?: string;
+    }>(path: Path, method: Method, init: InitWithUnknowns<Init>, options: Options, queryClient?: QueryClient): UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"]>, Options["select"]>, Response["error"]>;
+}
+export declare function useApiClientInfiniteQuery<Paths extends Record<string, any> = {}>(): ApiClientInfiniteQuery<Paths>;
+export {};

package/dist/hooks/use-infinite-query.js

@@ -0,0 +1,36 @@
+import { useInfiniteQuery as useTanstackInfiniteQuery, } from "@tanstack/react-query";
+import { useApiClient } from "../provider.js";
+import { buildQueryKey, parseArgs, } from "../utils.js";
+export function useApiClientInfiniteQuery() {
+    return useInfiniteQuery;
+}
+function useInfiniteQuery(path, ...args) {
+    const client = useApiClient();
+    const { method, rest } = parseArgs(args, "get");
+    const [init, options, queryClient] = rest;
+    const { pageParamName = "cursor", ...restOptions } = options;
+    const queryKey = buildQueryKey(method, path, init);
+    return useTanstackInfiniteQuery({
+        queryKey,
+        queryFn: async ({ pageParam = 0, signal }) => {
+            const mth = method.toUpperCase();
+            const fn = client[mth];
+            const mergedInit = {
+                ...init,
+                signal,
+                params: {
+                    ...(init?.params ?? undefined),
+                    query: {
+                        ...(init?.params?.query ?? undefined),
+                        [pageParamName]: pageParam,
+                    },
+                },
+            };
+            const { data, error } = await fn(path, mergedInit);
+            if (error)
+                throw error;
+            return data;
+        },
+        ...restOptions,
+    }, queryClient);
+}

package/dist/hooks/use-mutation.d.ts

@@ -0,0 +1,8 @@
+import { type QueryClient, type UseMutationOptions, type UseMutationResult } from "@tanstack/react-query";
+import type { FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod } from "@shipworthy/openapi-fetch";
+interface ApiClientMutation<Paths extends Record<string, any>> {
+    <Path extends PathsWithMethod<Paths, "post">, Init extends MaybeOptionalInit<Paths[Path], "post">, Response extends Required<FetchResponse<Paths[Path]["post"], Init, MediaType>>, Options extends Omit<UseMutationOptions<Response["data"], Response["error"], Init>, "mutationKey" | "mutationFn">>(path: Path, options?: Options, queryClient?: QueryClient): UseMutationResult<Response["data"], Response["error"], Init>;
+    <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method] & Record<string | number, any>, Init, MediaType>>, Options extends Omit<UseMutationOptions<Response["data"], Response["error"], Init>, "mutationKey" | "mutationFn">>(path: Path, method: Method, options?: Options, queryClient?: QueryClient): UseMutationResult<Response["data"], Response["error"], Init>;
+}
+export declare function useApiClientMutation<Paths extends Record<string, any> = {}>(): ApiClientMutation<Paths>;
+export {};

package/dist/hooks/use-mutation.js

@@ -0,0 +1,23 @@
+import { useMutation as useTanstackMutation, } from "@tanstack/react-query";
+import { useApiClient } from "../provider.js";
+import { parseArgs } from "../utils.js";
+export function useApiClientMutation() {
+    return useMutation;
+}
+function useMutation(path, ...args) {
+    const client = useApiClient();
+    const { method, rest } = parseArgs(args, "post");
+    const [options, queryClient] = rest;
+    return useTanstackMutation({
+        mutationKey: [method, path],
+        mutationFn: async (init) => {
+            const mth = method.toUpperCase();
+            const fn = client[mth];
+            const { data, error } = await fn(path, init);
+            if (error)
+                throw error;
+            return data;
+        },
+        ...(options ?? undefined),
+    }, queryClient);
+}

package/dist/hooks/use-query.d.ts

@@ -0,0 +1,20 @@
+import { type QueryClient, type SkipToken, type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+import type { FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod, RequiredKeysOf } from "@shipworthy/openapi-fetch";
+import { type InferSelectReturnType, type InitWithUnknowns, type QueryKey } from "../utils.ts";
+interface ApiClientQueryOptions<Paths extends Record<string, any>> {
+    <Path extends PathsWithMethod<Paths, "get">, Init extends MaybeOptionalInit<Paths[Path], "get">, Response extends Required<FetchResponse<Paths[Path]["get"], Init, MediaType>>, Options extends Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, "get", Path>>, "queryKey" | "queryFn">>(path: Path, ...[init, options]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?] : [InitWithUnknowns<Init>, Options?]): NoInfer<Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, "get", Path>>, "queryFn"> & {
+        queryFn: Exclude<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, "get", Path>>["queryFn"], SkipToken | undefined>;
+    }>;
+    <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method] & Record<string | number, any>, Init, MediaType>>, Options extends Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(path: Path, method: Method, ...[init, options]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?] : [InitWithUnknowns<Init>, Options?]): NoInfer<Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn"> & {
+        queryFn: Exclude<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, Method, Path>>["queryFn"], SkipToken | undefined>;
+    }>;
+}
+interface ApiClientQuery<Paths extends Record<string, any>> {
+    <Path extends PathsWithMethod<Paths, "get">, Init extends MaybeOptionalInit<Paths[Path], "get">, Response extends Required<FetchResponse<Paths[Path]["get"], Init, MediaType>>, Options extends Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, "get", Path>>, "queryKey" | "queryFn">>(path: Path, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?, QueryClient?] : [InitWithUnknowns<Init>, Options?, QueryClient?]): UseQueryResult<InferSelectReturnType<Response["data"], Options["select"]>, Response["error"]>;
+    <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method] & Record<string | number, any>, Init, MediaType>>, Options extends Omit<UseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(path: Path, method: Method, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?, QueryClient?] : [InitWithUnknowns<Init>, Options?, QueryClient?]): UseQueryResult<InferSelectReturnType<Response["data"], Options["select"]>, Response["error"]>;
+}
+/** Bind a schema first, then call the returned hook to infer each endpoint. */
+export declare function useApiClientQuery<Paths extends Record<string, any> = {}>(): ApiClientQuery<Paths>;
+/** Bind a schema first, then call the returned hook to build query options. */
+export declare function useApiClientQueryOptions<Paths extends Record<string, any> = {}>(): ApiClientQueryOptions<Paths>;
+export {};

package/dist/hooks/use-query.js

@@ -0,0 +1,31 @@
+import { useQuery as useTanstackQuery, } from "@tanstack/react-query";
+import { useApiClient } from "../provider.js";
+import { buildQueryFn, buildQueryKey, parseArgs, } from "../utils.js";
+/** Bind a schema first, then call the returned hook to infer each endpoint. */
+export function useApiClientQuery() {
+    return useQuery;
+}
+/** Bind a schema first, then call the returned hook to build query options. */
+export function useApiClientQueryOptions() {
+    return useQueryOptions;
+}
+function useQueryOptions(path, ...args) {
+    const client = useApiClient();
+    const { method, rest } = parseArgs(args, "get");
+    const [init, options] = rest;
+    return {
+        queryKey: buildQueryKey(method, path, init),
+        queryFn: buildQueryFn(client, method, path, init),
+        ...(options ?? undefined),
+    };
+}
+function useQuery(path, ...args) {
+    const client = useApiClient();
+    const { method, rest } = parseArgs(args, "get");
+    const [init, options, queryClient] = rest;
+    return useTanstackQuery({
+        queryKey: buildQueryKey(method, path, init),
+        queryFn: buildQueryFn(client, method, path, init),
+        ...(options ?? undefined),
+    }, queryClient);
+}

package/dist/hooks/use-suspense-query.d.ts

@@ -0,0 +1,10 @@
+import { type QueryClient, type UseSuspenseQueryOptions, type UseSuspenseQueryResult } from "@tanstack/react-query";
+import type { FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod, RequiredKeysOf } from "@shipworthy/openapi-fetch";
+import { type InferSelectReturnType, type InitWithUnknowns, type QueryKey } from "../utils.ts";
+interface ApiClientSuspenseQuery<Paths extends Record<string, any>> {
+    <Path extends PathsWithMethod<Paths, "get">, Init extends MaybeOptionalInit<Paths[Path], "get">, Response extends Required<FetchResponse<Paths[Path]["get"], Init, MediaType>>, Options extends Omit<UseSuspenseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, "get", Path>>, "queryKey" | "queryFn">>(path: Path, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?, QueryClient?] : [InitWithUnknowns<Init>, Options?, QueryClient?]): UseSuspenseQueryResult<InferSelectReturnType<Response["data"], Options["select"]>, Response["error"]>;
+    /** Explicit method overload */
+    <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<Paths[Path][Method] & Record<string | number, any>, Init, MediaType>>, Options extends Omit<UseSuspenseQueryOptions<Response["data"], Response["error"], InferSelectReturnType<Response["data"], Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(path: Path, method: Method, ...[init, options, queryClient]: RequiredKeysOf<Init> extends never ? [InitWithUnknowns<Init>?, Options?, QueryClient?] : [InitWithUnknowns<Init>, Options?, QueryClient?]): UseSuspenseQueryResult<InferSelectReturnType<Response["data"], Options["select"]>, Response["error"]>;
+}
+export declare function useApiClientSuspenseQuery<Paths extends Record<string, any> = {}>(): ApiClientSuspenseQuery<Paths>;
+export {};

package/dist/hooks/use-suspense-query.js

@@ -0,0 +1,16 @@
+import { useSuspenseQuery as useTanstackSuspenseQuery, } from "@tanstack/react-query";
+import { useApiClient } from "../provider.js";
+import { buildQueryFn, buildQueryKey, parseArgs, } from "../utils.js";
+export function useApiClientSuspenseQuery() {
+    return useSuspenseQuery;
+}
+function useSuspenseQuery(path, ...args) {
+    const client = useApiClient();
+    const { method, rest } = parseArgs(args, "get");
+    const [init, options, queryClient] = rest;
+    return useTanstackSuspenseQuery({
+        queryKey: buildQueryKey(method, path, init),
+        queryFn: buildQueryFn(client, method, path, init),
+        ...(options ?? undefined),
+    }, queryClient);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createApiClient } from "./client.ts";
+export type { ApiClient } from "./client.ts";
+export { ApiClientProvider, useApiClient } from "./provider.tsx";
+export { useApiClientQueryOptions, useApiClientQuery } from "./hooks/use-query.ts";
+export { useApiClientSuspenseQuery } from "./hooks/use-suspense-query.ts";
+export { useApiClientInfiniteQuery } from "./hooks/use-infinite-query.ts";
+export { useApiClientMutation } from "./hooks/use-mutation.ts";
+export type { QueryKey } from "./utils.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createApiClient } from "./client.js";
+export { ApiClientProvider, useApiClient } from "./provider.js";
+export { useApiClientQueryOptions, useApiClientQuery } from "./hooks/use-query.js";
+export { useApiClientSuspenseQuery } from "./hooks/use-suspense-query.js";
+export { useApiClientInfiniteQuery } from "./hooks/use-infinite-query.js";
+export { useApiClientMutation } from "./hooks/use-mutation.js";

package/dist/provider.d.ts

@@ -0,0 +1,8 @@
+import { type PropsWithChildren } from "react";
+import { QueryClient } from "@tanstack/react-query";
+import { type Client } from "@shipworthy/openapi-fetch";
+export declare function useApiClient<Paths extends {} = {}>(): Client<Paths>;
+export declare function ApiClientProvider({ children, baseUrl, queryClient, }: PropsWithChildren<{
+    baseUrl: string;
+    queryClient?: QueryClient;
+}>): import("react").JSX.Element;

package/dist/provider.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { isServer, QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import createClient from "@shipworthy/openapi-fetch";
+const ApiClientContext = createContext(null);
+export function useApiClient() {
+    const client = useContext(ApiClientContext);
+    if (!client)
+        throw new Error("useApiClient must be used within ApiClientProvider");
+    return client;
+}
+function makeQueryClient() {
+    return new QueryClient({
+        defaultOptions: { queries: { staleTime: 60 * 1000 } },
+    });
+}
+let browserQueryClient;
+function getQueryClient() {
+    if (isServer)
+        return makeQueryClient();
+    if (!browserQueryClient)
+        browserQueryClient = makeQueryClient();
+    return browserQueryClient;
+}
+export function ApiClientProvider({ children, baseUrl, queryClient = getQueryClient(), }) {
+    const client = createClient({ baseUrl });
+    return (_jsx(ApiClientContext.Provider, { value: client, children: _jsx(QueryClientProvider, { client: queryClient, children: children }) }));
+}

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { Client, HttpMethod, MaybeOptionalInit, PathsWithMethod } from "@shipworthy/openapi-fetch";
+export type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer R ? R : TData;
+export type InitWithUnknowns<Init> = Init & {
+    [key: string]: unknown;
+};
+export type QueryKey<Paths extends Record<string, any>, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init = MaybeOptionalInit<Paths[Path], Method>> = Init extends undefined ? readonly [Method, Path] : readonly [Method, Path, Init];
+export declare function parseArgs(args: unknown[], defaultMethod: HttpMethod): {
+    method: HttpMethod;
+    rest: unknown[];
+};
+export declare function buildQueryFn(client: Client<{}>, method: HttpMethod, path: string, init: unknown): ({ signal }: {
+    signal: AbortSignal;
+}) => Promise<any>;
+export declare function buildQueryKey(method: HttpMethod, path: string, init: unknown): readonly [HttpMethod, string] | readonly [HttpMethod, string, {} | null];

package/dist/utils.js

@@ -0,0 +1,26 @@
+export function parseArgs(args, defaultMethod) {
+    if (typeof args[0] === "string") {
+        const [method, ...rest] = args;
+        return { method: method, rest };
+    }
+    return { method: defaultMethod, rest: args };
+}
+export function buildQueryFn(client, method, path, init) {
+    return async ({ signal }) => {
+        const mth = method.toUpperCase();
+        const fn = client[mth];
+        const { data, error, response } = await fn(path, {
+            signal,
+            ...(init ?? undefined),
+        });
+        if (error)
+            throw error;
+        if (response.status === 204 || response.headers.get("Content-Length") === "0") {
+            return data ?? null;
+        }
+        return data;
+    };
+}
+export function buildQueryKey(method, path, init) {
+    return init === undefined ? [method, path] : [method, path, init];
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@shipworthy/openapi-react-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@shipworthy/openapi-fetch": "0.0.1"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.104.1",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipWorthyAI/openapi.git",
+    "directory": "packages/openapi-react-query"
+  },
+  "type": "module",
+  "react-native": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@shipworthy/typescript-config": "0.0.1",
+    "@tanstack/react-query": "^5.104.1",
+    "@types/node": "^24.10.3",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^7.0.2"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}