@ryneex/api-client 0.0.51 → 1.0.0-beta.0

package/README.md

@@ -1,15 +1,377 @@
-# api-client
+# @ryneex/api-client
 
-To install dependencies:
+Type-safe API client built on **Axios**, **Zod**, and **TanStack Query**. Define endpoints with request/response validation and get ready-to-use `call`, `queryOptions`, and `mutationOptions` for React Query.
+
+---
+
+## Installation
 
 ```bash
-bun install
+bun add @ryneex/api-client axios zod @tanstack/react-query
+# or
+npm i @ryneex/api-client axios zod @tanstack/react-query
 ```
 
-To run:
+**Peer dependencies:** `axios` ^1.13.2, `zod` ^4, `@tanstack/react-query` ^5, `typescript` ^5.
 
-```bash
-bun run src/index.ts
+---
+
+## Quick start
+
+```ts
+import axios from "axios";
+import z from "zod";
+import { createClient } from "@ryneex/api-client";
+
+const axiosInstance = axios.create({
+  baseURL: "https://api.example.com",
+  headers: { "Content-Type": "application/json" },
+});
+
+const client = createClient(axiosInstance);
+
+// Define a GET endpoint with validated response
+const getUsers = client.create({
+  method: "GET",
+  path: "/users",
+  outputSchema: z.object({
+    users: z.array(
+      z.object({ id: z.string(), name: z.string(), email: z.string() }),
+    ),
+  }),
+});
+
+// Call it (returns AxiosResponse<inferred output type>)
+const res = await getUsers();
+console.log(res.data.users);
+
+// Or use with React Query
+import { useQuery } from "@tanstack/react-query";
+const { data } = useQuery(getUsers.queryOptions());
+```
+
+---
+
+## Creating the client
+
+Use any **Axios instance** (with base URL, auth, interceptors, etc.) with `createClient`:
+
+```ts
+import axios from "axios";
+import { createClient } from "@ryneex/api-client";
+
+const axiosInstance = axios.create({
+  baseURL: "https://api.example.com/v1",
+  timeout: 10_000,
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${process.env.API_TOKEN}`,
+  },
+});
+
+const client = createClient(axiosInstance);
+```
+
+---
+
+## Defining endpoints: `client.create`
+
+`client.create` takes:
+
+| Option            | Type                                    | Required | Description                                        |
+| ----------------- | --------------------------------------- | -------- | -------------------------------------------------- |
+| `method`          | `GET \| POST \| PUT \| PATCH \| DELETE` | Yes      | HTTP method.                                       |
+| `path`            | `string \| (data) => string`            | Yes      | URL path (static or derived from input/variables). |
+| `outputSchema`    | `z.ZodType`                             | Yes      | Zod schema for response body; type is inferred.    |
+| `inputSchema`     | `z.ZodType`                             | No       | Schema for `data.input` (e.g. body for POST).      |
+| `variablesSchema` | `z.ZodType`                             | No       | Schema for `data.variables` (e.g. path/query).     |
+| `axiosOptions`    | `(data) => AxiosRequestConfig`          | No       | Extra Axios config (headers, params, data, etc.).  |
+| `transform`       | `(data, payload) => TOutput`            | No       | Optional post-processing of parsed response data.  |
+
+The returned endpoint is a **callable function** with helpers:
+
+- **Direct call** — call `await endpoint(payload?)` to perform the request; returns `Promise<AxiosResponse<TOutput>>`.
+- **`queryOptions(opts?)`** — `UseQueryOptions` for `useQuery`.
+- **`mutationOptions(opts?)`** — `UseMutationOptions` for `useMutation`.
+- **`config`** — `{ method, path, outputSchema, inputSchema?, variablesSchema? }`.
+
+---
+
+## Example: GET with no input
+
+```ts
+const getProducts = client.create({
+  method: "GET",
+  path: "/products",
+  outputSchema: z.object({
+    products: z.array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        price: z.number(),
+      }),
+    ),
+  }),
+});
+
+// Direct call
+const { data } = await getProducts();
+// data is { products: { id, title, price }[] }
+
+// React Query
+const { data } = useQuery(getProducts.queryOptions());
+```
+
+---
+
+## Example: GET with variables (path/query)
+
+Use `variablesSchema` and a **path function** when the URL or query depends on parameters:
+
+```ts
+const getUserById = client.create({
+  method: "GET",
+  path: (data) => `/users/${data.variables.userId}`,
+  variablesSchema: z.object({ userId: z.string() }),
+  outputSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+});
+
+// Direct call — pass { variables: { userId: "123" } }
+const { data } = await getUserById({ variables: { userId: "123" } });
+
+// React Query — must pass data so queryKey and queryFn get userId
+const { data } = useQuery(
+  getUserById.queryOptions({
+    data: { variables: { userId: "123" } },
+    staleTime: 60_000,
+  }),
+);
+```
+
+---
+
+## Example: POST with request body (input)
+
+Use `inputSchema` for the body and optionally `axiosOptions` to pass it to Axios:
+
+```ts
+const createUser = client.create({
+  method: "POST",
+  path: "/users",
+  inputSchema: z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  axiosOptions: (data) => ({
+    data: data.input,
+  }),
+});
+
+// Direct call
+const { data } = await createUser({
+  input: { name: "Jane", email: "jane@example.com" },
+});
+
+// React Query mutation
+const mutation = useMutation(
+  createUser.mutationOptions({
+    onSuccess: (user) => console.log("Created", user),
+  }),
+);
+mutation.mutate({ input: { name: "Jane", email: "jane@example.com" } });
+```
+
+---
+
+## Example: Dynamic path and query params
+
+Combine variables with a path function and `axiosOptions` for query params:
+
+```ts
+const listUsers = client.create({
+  method: "GET",
+  path: "/users",
+  variablesSchema: z.object({
+    page: z.number().optional(),
+    limit: z.number().optional(),
+  }),
+  outputSchema: z.object({
+    users: z.array(z.object({ id: z.string(), name: z.string() })),
+    total: z.number(),
+  }),
+  axiosOptions: (data) => ({
+    params: data.variables,
+  }),
+});
+
+const { data } = await listUsers({
+  variables: { page: 1, limit: 10 },
+});
+```
+
+---
+
+## Example: PUT / PATCH / DELETE
+
+Same pattern: use `inputSchema` for body and `axiosOptions` to pass it.
+
+```ts
+const updateUser = client.create({
+  method: "PATCH",
+  path: (data) => `/users/${data.variables.userId}`,
+  variablesSchema: z.object({ userId: z.string() }),
+  inputSchema: z.object({
+    name: z.string().optional(),
+    email: z.string().email().optional(),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  axiosOptions: (data) => ({
+    data: data.input,
+  }),
+});
+
+await updateUser({
+  variables: { userId: "123" },
+  input: { name: "New Name" },
+});
+```
+
+---
+
+## Using with React Query
+
+### Queries (GET)
+
+- Use **`queryOptions({ data?, ...useQueryOptions })`**.
+- If the endpoint has **input or variables**, pass **`data`** so both `queryKey` and `queryFn` receive it.
+- You can pass any `useQuery` options (`staleTime`, `enabled`, etc.) and optional **`onSuccess`** / **`onError`** with the same payload shape.
+
+```ts
+// No input/variables
+useQuery(getProducts.queryOptions({ staleTime: 60_000 }));
+
+// With variables (e.g. GET by id)
+useQuery(
+  getUserById.queryOptions({
+    data: { variables: { userId: "123" } },
+    enabled: !!userId,
+    onSuccess: (user) => {},
+    onError: (err, { variables }) => {},
+  }),
+);
+```
+
+### Mutations (POST / PUT / PATCH / DELETE)
+
+- Use **`mutationOptions(options?)`** with `useMutation`.
+- **`mutation.mutate(data)`** must match the endpoint’s `input`/`variables` shape.
+
+```ts
+const mutation = useMutation(
+  createUser.mutationOptions({
+    onSuccess: (user) => {},
+    onError: (error, variables) => {},
+  }),
+);
+
+mutation.mutate({
+  input: { name: "Jane", email: "jane@example.com" },
+});
+```
+
+---
+
+## Validation and errors
+
+- **Input** and **variables** are validated with Zod before the request; invalid data throws **`ZodError`**.
+- **Response** is parsed with `outputSchema` after the request; invalid response throws **`ZodError`**.
+- Network or server errors are **AxiosError**.
+
+So the callable and React Query helpers can throw **`ZodError | AxiosError`**. Handle both in `onError` or in try/catch:
+
+```ts
+import { AxiosError } from "axios";
+import { ZodError } from "zod";
+
+const { data, error } = useQuery(
+  getUsers.queryOptions({
+    onError: (err) => {
+      if (err instanceof ZodError) {
+        console.error("Validation failed", err.flatten());
+      } else if (err instanceof AxiosError) {
+        console.error("Request failed", err.response?.status);
+      }
+    },
+  }),
+);
 ```
 
-This project was created using `bun init` in bun v1.3.0. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+---
+
+## Full example: small API module
+
+```ts
+import axios from "axios";
+import z from "zod";
+import { createClient } from "@ryneex/api-client";
+
+const axiosInstance = axios.create({
+  baseURL: "https://api.example.com",
+  headers: { "Content-Type": "application/json" },
+});
+
+const client = createClient(axiosInstance);
+
+// Schemas
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+});
+
+// GET /users
+export const getUsers = client.create({
+  method: "GET",
+  path: "/users",
+  outputSchema: z.object({ users: z.array(userSchema) }),
+});
+
+// GET /users/:id
+export const getUser = client.create({
+  method: "GET",
+  path: (d) => `/users/${d.variables.id}`,
+  variablesSchema: z.object({ id: z.string() }),
+  outputSchema: userSchema,
+});
+
+// POST /users
+export const createUser = client.create({
+  method: "POST",
+  path: "/users",
+  inputSchema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  outputSchema: userSchema,
+  axiosOptions: (d) => ({ data: d.input }),
+});
+
+// Usage in a component
+// const { data } = useQuery(getUsers.queryOptions());
+// const { data } = useQuery(getUser.queryOptions({ data: { variables: { id: "1" } } }));
+// const mutation = useMutation(createUser.mutationOptions());
+// mutation.mutate({ input: { name: "Jane", email: "jane@example.com" } });
+```

package/index.d.ts

@@ -1,35 +1,49 @@
-import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
-import { AxiosInstance, AxiosRequestConfig, AxiosResponse, AxiosError } from 'axios';
+import * as axios from 'axios';
+import { AxiosRequestConfig, AxiosError, AxiosInstance } from 'axios';
 import z, { ZodError } from 'zod';
+import { UseQueryOptions, UseMutationOptions } from '@tanstack/react-query';
+
+type ClientPayload<TInput, TVariables> = {} & (unknown extends TInput ? unknown : {
+    input: TInput;
+}) & (unknown extends TVariables ? unknown : {
+    variables: TVariables;
+});
+type OptionalPayload<T> = object extends T ? void : T;
+type ClientOptions<TOutputSchema extends z.ZodType, TInputSchema extends z.ZodType, TVariablesSchema extends z.ZodType, TOutput = z.infer<TOutputSchema>, TInput = z.infer<TInputSchema>, TVariables = z.infer<TVariablesSchema>> = {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string | ((payload: ClientPayload<TInput, TVariables>) => string);
+    axiosOptions?: (payload: ClientPayload<TInput, TVariables>) => AxiosRequestConfig;
+    variablesSchema?: TVariablesSchema;
+    inputSchema?: TInputSchema;
+    outputSchema: TOutputSchema;
+    transform?: (data: z.infer<TOutputSchema>, payload: ClientPayload<TInput, TVariables>) => TOutput;
+};
 
-type ReactQueryOptions<TResponse, TData = void> = Omit<UseQueryOptions<TResponse, ZodError<TResponse> | AxiosError>, "queryFn" | "queryKey"> & {
+type ReactQueryOptions<TOutput, TInput, TVariables> = Omit<UseQueryOptions<TOutput, ZodError<TOutput> | AxiosError>, "queryFn" | "queryKey"> & {
     queryKey?: unknown[];
-} & (TData extends void ? {
-    data?: void;
-} : {
-    data: TData;
+} & (object extends ClientPayload<TInput, TVariables> ? unknown : {
+    data: ClientPayload<TInput, TVariables>;
 }) & {
-    onSuccess?: (data: TResponse, variables: TData) => void;
-    onError?: (error: ZodError<TResponse> | AxiosError, variables: TData) => void;
+    onSuccess?: (data: TOutput, payload: ClientPayload<TInput, TVariables>) => void;
+    onError?: (error: ZodError<TOutput> | AxiosError, payload: ClientPayload<TInput, TVariables>) => void;
 };
-type ReactMutationOptions<TResponse, TData = void> = Omit<UseMutationOptions<TResponse, ZodError<TResponse> | AxiosError, TData>, "mutationFn" | "mutationKey"> & {
-    mutationKey?: unknown[];
-};
-declare class BaseApiClient {
-    readonly axios: AxiosInstance;
-    constructor(axios: AxiosInstance);
-    createEndpoint<TResponse, TData = void>({ method, path, axiosOptions: axiosOptionsFn, dataSchema, responseSchema, }: {
-        method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-        path: string | ((data: TData) => string);
-        axiosOptions?: (data: TData) => AxiosRequestConfig;
-        dataSchema?: z.ZodType<TData>;
-        responseSchema: z.ZodType<TResponse>;
-    }): ((data: TData) => Promise<AxiosResponse<TResponse>>) & {
-        queryKey: (data: TData | void) => (string | NonNullable<TData>)[];
-        queryOptions: (opts: TData extends void ? ReactQueryOptions<TResponse> | void : ReactQueryOptions<TResponse, TData>) => UseQueryOptions<TResponse, ZodError<TResponse> | AxiosError>;
-        mutationKey: () => string[];
-        mutationOptions: (opts: ReactMutationOptions<TResponse, TData> | void) => UseMutationOptions<TResponse, ZodError<TResponse> | AxiosError, TData>;
+type ReactMutationOptions<TOutput, TInput, TVariables> = Omit<UseMutationOptions<TOutput, ZodError<TOutput> | AxiosError, object extends ClientPayload<TInput, TVariables> ? void : ClientPayload<TInput, TVariables>>, "mutationFn"> & {};
+
+declare function createClient(axios: AxiosInstance): {
+    create: <TOutputSchema extends z.ZodType, TInputSchema extends z.ZodType, TVariablesSchema extends z.ZodType, TOutput = z.core.output<TOutputSchema>, TInput = z.core.output<TInputSchema>, TVariables = z.core.output<TVariablesSchema>>(opts: ClientOptions<TOutputSchema, TInputSchema, TVariablesSchema, TOutput, TInput, TVariables>) => ((_payload: OptionalPayload<ClientPayload<TInput, TVariables>>) => Promise<axios.AxiosResponse<TOutput, any, {}>>) & {
+        queryOptions: (_opts: object extends ClientPayload<TInput, TVariables> ? ReactQueryOptions<TOutput, TInput, TVariables> | void : ReactQueryOptions<TOutput, TInput, TVariables>) => UseQueryOptions<TOutput, ZodError<TOutput> | AxiosError>;
+        mutationOptions: (_opts: ReactMutationOptions<TOutput, TInput, TVariables> | void) => UseMutationOptions<TOutput, ZodError<TOutput> | AxiosError, object extends ClientPayload<TInput, TVariables> ? void : ClientPayload<TInput, TVariables>>;
+        config: {
+            inputSchema: undefined extends TInputSchema ? undefined : NonNullable<TInputSchema>;
+            variablesSchema: undefined extends TVariablesSchema ? undefined : NonNullable<TVariablesSchema>;
+            axios: AxiosInstance;
+            method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+            path: string | ((payload: ClientPayload<TInput, TVariables>) => string);
+            axiosOptions?: ((payload: ClientPayload<TInput, TVariables>) => axios.AxiosRequestConfig) | undefined;
+            outputSchema: TOutputSchema;
+            transform?: ((data: z.core.output<TOutputSchema>, payload: ClientPayload<TInput, TVariables>) => TOutput) | undefined;
+        };
     };
-}
+};
 
-export { BaseApiClient };
+export { createClient };

package/index.js

@@ -1,79 +1,84 @@
-// src/lib/base-api-client.ts
-import "@tanstack/react-query";
+// src/lib/api-client.ts
+import "zod";
+
+// src/lib/call-api.ts
 import "zod";
-var BaseApiClient = class {
-  axios;
-  constructor(axios) {
-    this.axios = axios;
+async function callApi(opts, data) {
+  if (typeof data !== "object")
+    throw new Error("API SDK: Data must be an object");
+  if (opts.inputSchema && "input" in data) {
+    opts.inputSchema.parse(data.input);
+  }
+  if (opts.variablesSchema && "variables" in data) {
+    opts.variablesSchema.parse(data.variables);
+  }
+  const axiosOptions = opts.axiosOptions?.(data);
+  const url = typeof opts.path === "function" ? opts.path(data) : opts.path;
+  if (opts.method === "GET") {
+    const response = await opts.axios.get(url, axiosOptions);
+    return getResponse(opts, data, response);
+  }
+  if (opts.method === "POST") {
+    const response = await opts.axios.post(
+      url,
+      axiosOptions?.data,
+      axiosOptions
+    );
+    return getResponse(opts, data, response);
+  }
+  if (opts.method === "PUT") {
+    const response = await opts.axios.put(
+      url,
+      axiosOptions?.data,
+      axiosOptions
+    );
+    return getResponse(opts, data, response);
+  }
+  if (opts.method === "PATCH") {
+    const response = await opts.axios.patch(
+      url,
+      axiosOptions?.data,
+      axiosOptions
+    );
+    return getResponse(opts, data, response);
+  }
+  if (opts.method === "DELETE") {
+    const response = await opts.axios.delete(url, axiosOptions);
+    return getResponse(opts, data, response);
+  }
+  throw new Error(`API SDK: Unsupported method: ${opts.method}`);
+}
+function getResponse(opts, payload, response) {
+  const parsedData = opts.outputSchema.parse(response.data);
+  if (opts.transform) {
+    return { ...response, data: opts.transform(parsedData, payload) };
   }
-  createEndpoint({
-    method,
-    path,
-    axiosOptions: axiosOptionsFn,
-    dataSchema,
-    responseSchema
-  }) {
+  return { ...response, data: parsedData };
+}
+
+// src/lib/api-client.ts
+import "@tanstack/react-query";
+function createClient(axios) {
+  function create(opts) {
     const uuid = crypto.randomUUID();
-    const call = async (data) => {
-      if (dataSchema) {
-        dataSchema.parse(data);
-      }
-      const axiosOptions = axiosOptionsFn?.(data);
-      const url = typeof path === "function" ? path(data) : path;
-      if (method === "GET") {
-        const response = await this.axios.get(url, axiosOptions);
-        responseSchema.parse(response.data);
-        return response;
-      }
-      if (method === "POST") {
-        const response = await this.axios.post(
-          url,
-          axiosOptions?.data,
-          axiosOptions
-        );
-        responseSchema.parse(response.data);
-        return response;
-      }
-      if (method === "PUT") {
-        const response = await this.axios.put(
-          url,
-          axiosOptions?.data,
-          axiosOptions
-        );
-        responseSchema.parse(response.data);
-        return response;
-      }
-      if (method === "PATCH") {
-        const response = await this.axios.patch(
-          url,
-          axiosOptions?.data,
-          axiosOptions
-        );
-        responseSchema.parse(response.data);
-        return response;
-      }
-      if (method === "DELETE") {
-        const response = await this.axios.delete(url, axiosOptions);
-        responseSchema.parse(response.data);
-        return response;
-      }
-      throw new Error(`API SDK: Unsupported method: ${method}`);
+    const apiOptionas = { ...opts, axios };
+    const call = async (_payload) => {
+      const payload = _payload ?? {};
+      return callApi(apiOptionas, payload);
     };
     const queryKey = (data) => data ? ["api-call", "query", uuid, data] : ["api-call", "query", uuid];
     const mutationKey = () => ["api-call", "mutation", uuid];
-    const queryOptions = (opts) => {
-      const { data, ...options } = opts ?? {};
+    const queryOptions = (_opts) => {
+      const { data: _data, ...options } = _opts ?? {};
+      const data = _data ?? {};
       return {
         queryFn: async () => {
           try {
-            const response = await call(data);
+            const response = await callApi(apiOptionas, data);
             options.onSuccess?.(response.data, data);
             return response.data;
           } catch (error) {
-            options.onError?.(
-              error,
-              data
-            );
+            options.onError?.(error, data);
             throw error;
           }
         },
@@ -81,11 +86,12 @@ var BaseApiClient = class {
         ...options
       };
     };
-    const mutationOptions = (opts) => {
-      const options = opts ?? {};
+    const mutationOptions = (_opts) => {
+      const options = _opts ?? {};
       return {
-        mutationFn: async (data) => {
-          const response = await call(data);
+        mutationFn: async (_data) => {
+          const data = _data ?? {};
+          const response = await callApi(apiOptionas, data);
           return response.data;
         },
         mutationKey: mutationKey(),
@@ -93,13 +99,17 @@ var BaseApiClient = class {
       };
     };
     return Object.assign(call, {
-      queryKey,
       queryOptions,
-      mutationKey,
-      mutationOptions
+      mutationOptions,
+      config: {
+        ...apiOptionas,
+        inputSchema: opts.inputSchema,
+        variablesSchema: opts.variablesSchema
+      }
     });
   }
-};
+  return { create };
+}
 export {
-  BaseApiClient
+  createClient
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@ryneex/api-client",
   "module": "src/index.ts",
   "type": "module",
-  "version": "0.0.51",
+  "version": "1.0.0-beta.0",
   "exports": {
     ".": "./index.js"
   },