@simplix-react/contract 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,62 +1,474 @@
 import { z } from 'zod';
 
+/**
+ * Describes a single sort directive with field name and direction.
+ *
+ * @example
+ * ```ts
+ * import type { SortParam } from "@simplix-react/contract";
+ *
+ * const sort: SortParam = { field: "createdAt", direction: "desc" };
+ * ```
+ */
+interface SortParam {
+    /** The field name to sort by. */
+    field: string;
+    /** Sort direction: ascending or descending. */
+    direction: "asc" | "desc";
+}
+/**
+ * Describes pagination strategy, supporting both offset-based and cursor-based patterns.
+ *
+ * @example
+ * ```ts
+ * import type { PaginationParam } from "@simplix-react/contract";
+ *
+ * // Offset-based
+ * const offset: PaginationParam = { type: "offset", page: 1, limit: 20 };
+ *
+ * // Cursor-based
+ * const cursor: PaginationParam = { type: "cursor", cursor: "abc123", limit: 20 };
+ * ```
+ */
+type PaginationParam = {
+    type: "offset";
+    page: number;
+    limit: number;
+} | {
+    type: "cursor";
+    cursor: string;
+    limit: number;
+};
+/**
+ * Encapsulates all list query parameters: filters, sorting, and pagination.
+ *
+ * Passed to entity `list()` methods and serialized into URL search params
+ * by a {@link QueryBuilder}.
+ *
+ * @typeParam TFilters - Shape of the filter object, defaults to `Record<string, unknown>`.
+ *
+ * @example
+ * ```ts
+ * import type { ListParams } from "@simplix-react/contract";
+ *
+ * const params: ListParams = {
+ *   filters: { status: "active" },
+ *   sort: { field: "title", direction: "asc" },
+ *   pagination: { type: "offset", page: 1, limit: 10 },
+ * };
+ *
+ * await api.client.task.list(params);
+ * ```
+ */
+interface ListParams<TFilters = Record<string, unknown>> {
+    /** Optional filter criteria applied to the list query. */
+    filters?: TFilters;
+    /** Single sort directive or array of sort directives. */
+    sort?: SortParam | SortParam[];
+    /** Pagination strategy and parameters. */
+    pagination?: PaginationParam;
+}
+/**
+ * Describes pagination metadata returned from the server.
+ *
+ * Used by {@link QueryBuilder.parsePageInfo} to extract pagination state
+ * from API responses, enabling infinite scroll and paginated UIs.
+ *
+ * @example
+ * ```ts
+ * import type { PageInfo } from "@simplix-react/contract";
+ *
+ * const pageInfo: PageInfo = {
+ *   total: 42,
+ *   hasNextPage: true,
+ *   nextCursor: "cursor-xyz",
+ * };
+ * ```
+ */
+interface PageInfo {
+    /** Total number of items across all pages (if the server provides it). */
+    total?: number;
+    /** Whether more items exist beyond the current page. */
+    hasNextPage: boolean;
+    /** Cursor value to fetch the next page (cursor-based pagination only). */
+    nextCursor?: string;
+}
+/**
+ * Defines how list parameters are serialized to URL search params and how
+ * pagination metadata is extracted from API responses.
+ *
+ * Implement this interface to adapt the framework to your API's query string
+ * conventions. Use {@link simpleQueryBuilder} as a ready-made implementation
+ * for common REST patterns.
+ *
+ * @example
+ * ```ts
+ * import type { QueryBuilder } from "@simplix-react/contract";
+ *
+ * const customQueryBuilder: QueryBuilder = {
+ *   buildSearchParams(params) {
+ *     const sp = new URLSearchParams();
+ *     if (params.pagination?.type === "offset") {
+ *       sp.set("offset", String((params.pagination.page - 1) * params.pagination.limit));
+ *       sp.set("limit", String(params.pagination.limit));
+ *     }
+ *     return sp;
+ *   },
+ *   parsePageInfo(response) {
+ *     const { total, nextCursor } = response as any;
+ *     return { total, hasNextPage: !!nextCursor, nextCursor };
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link simpleQueryBuilder} for the built-in implementation.
+ */
+interface QueryBuilder {
+    /** Converts structured list parameters into URL search params. */
+    buildSearchParams(params: ListParams): URLSearchParams;
+    /** Extracts pagination metadata from an API response (optional). */
+    parsePageInfo?(response: unknown): PageInfo;
+}
+
+/**
+ * Describes the parent resource in a nested entity relationship.
+ *
+ * Enables hierarchical URL construction such as `/projects/:projectId/tasks`.
+ *
+ * @example
+ * ```ts
+ * const parent: EntityParent = {
+ *   param: "projectId",
+ *   path: "/projects",
+ * };
+ * // Produces: /projects/:projectId/tasks
+ * ```
+ *
+ * @see {@link EntityDefinition} for the entity that references this parent.
+ */
 interface EntityParent {
+    /** Route parameter name used to identify the parent resource (e.g. `"projectId"`). */
     param: string;
+    /** Base path segment for the parent resource (e.g. `"/projects"`). */
     path: string;
 }
+/**
+ * Represents a named query scope that filters entities by a parent relationship.
+ *
+ * Allows defining reusable query patterns like "tasks by project" that can be
+ * referenced throughout the application.
+ *
+ * @see {@link EntityDefinition.queries} where these are declared.
+ */
 interface EntityQuery {
+    /** Name of the parent entity this query filters by (e.g. `"project"`). */
     parent: string;
+    /** Route parameter name used to scope the query (e.g. `"projectId"`). */
     param: string;
 }
+/**
+ * Defines a CRUD-capable API entity with Zod schemas for type-safe validation.
+ *
+ * Serves as the single source of truth for an entity's shape, creation payload,
+ * update payload, and URL structure. The framework derives API clients, React Query
+ * hooks, and MSW handlers from this definition.
+ *
+ * @typeParam TSchema - Zod schema for the entity's response shape.
+ * @typeParam TCreate - Zod schema for the creation payload.
+ * @typeParam TUpdate - Zod schema for the update (partial) payload.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import type { EntityDefinition } from "@simplix-react/contract";
+ *
+ * const taskEntity: EntityDefinition = {
+ *   path: "/tasks",
+ *   schema: z.object({ id: z.string(), title: z.string() }),
+ *   createSchema: z.object({ title: z.string() }),
+ *   updateSchema: z.object({ title: z.string().optional() }),
+ *   parent: { param: "projectId", path: "/projects" },
+ * };
+ * ```
+ *
+ * @see {@link OperationDefinition} for non-CRUD custom operations.
+ * @see {@link @simplix-react/react!deriveHooks | deriveHooks} for deriving React Query hooks.
+ * @see {@link @simplix-react/mock!deriveMockHandlers | deriveMockHandlers} for deriving MSW handlers.
+ */
 interface EntityDefinition<TSchema extends z.ZodType = z.ZodType, TCreate extends z.ZodType = z.ZodType, TUpdate extends z.ZodType = z.ZodType> {
+    /** URL path segment for this entity (e.g. `"/tasks"`). */
     path: string;
+    /** Zod schema describing the full entity shape returned by the API. */
     schema: TSchema;
+    /** Zod schema describing the payload required to create a new entity. */
     createSchema: TCreate;
+    /** Zod schema describing the payload for updating an existing entity. */
     updateSchema: TUpdate;
+    /** Optional parent resource for nested URL construction. */
     parent?: EntityParent;
+    /** Named query scopes for filtering entities by parent relationships. */
     queries?: Record<string, EntityQuery>;
+    /** Optional Zod schema for validating list filter parameters. */
+    filterSchema?: z.ZodType;
 }
+/**
+ * Supported HTTP methods for API operations.
+ */
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Defines a custom (non-CRUD) API operation with typed input and output.
+ *
+ * Covers endpoints that do not fit the standard entity CRUD pattern, such as
+ * file uploads, batch operations, or RPC-style calls. Path parameters use
+ * the `:paramName` syntax and are positionally mapped to function arguments.
+ *
+ * @typeParam TInput - Zod schema for the request payload.
+ * @typeParam TOutput - Zod schema for the response payload.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import type { OperationDefinition } from "@simplix-react/contract";
+ *
+ * const assignTask: OperationDefinition = {
+ *   method: "POST",
+ *   path: "/tasks/:taskId/assign",
+ *   input: z.object({ userId: z.string() }),
+ *   output: z.object({ id: z.string(), assigneeId: z.string() }),
+ * };
+ * ```
+ *
+ * @see {@link EntityDefinition} for standard CRUD entities.
+ */
 interface OperationDefinition<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
+    /** HTTP method for this operation. */
     method: HttpMethod;
+    /** URL path with optional `:paramName` placeholders (e.g. `"/tasks/:taskId/assign"`). */
     path: string;
+    /** Zod schema validating the request payload. */
     input: TInput;
+    /** Zod schema validating the response payload. */
     output: TOutput;
+    /** Content type for the request body. Defaults to `"json"`. */
+    contentType?: "json" | "multipart";
+    /** Expected response format. Defaults to `"json"`. */
+    responseType?: "json" | "blob";
+    /**
+     * Returns query key arrays that should be invalidated after this operation succeeds.
+     * Enables automatic cache invalidation in `@simplix-react/react`.
+     */
     invalidates?: (queryKeys: Record<string, QueryKeyFactory>, params: Record<string, string>) => readonly unknown[][];
 }
+/**
+ * Configures a complete API contract with entities, operations, and shared settings.
+ *
+ * Serves as the input to {@link defineApi}, grouping all entity and operation
+ * definitions under a single domain namespace with a shared base path.
+ *
+ * @typeParam TEntities - Map of entity names to their definitions.
+ * @typeParam TOperations - Map of operation names to their definitions.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { simpleQueryBuilder } from "@simplix-react/contract";
+ * import type { ApiContractConfig } from "@simplix-react/contract";
+ *
+ * const config: ApiContractConfig = {
+ *   domain: "project",
+ *   basePath: "/api/v1",
+ *   entities: {
+ *     task: {
+ *       path: "/tasks",
+ *       schema: z.object({ id: z.string(), title: z.string() }),
+ *       createSchema: z.object({ title: z.string() }),
+ *       updateSchema: z.object({ title: z.string().optional() }),
+ *     },
+ *   },
+ *   queryBuilder: simpleQueryBuilder,
+ * };
+ * ```
+ *
+ * @see {@link defineApi} for constructing a contract from this config.
+ */
 interface ApiContractConfig<TEntities extends Record<string, EntityDefinition<any, any, any>> = Record<string, EntityDefinition>, TOperations extends Record<string, OperationDefinition<any, any>> = Record<string, OperationDefinition>> {
+    /** Logical domain name used as the root segment in query keys (e.g. `"project"`). */
     domain: string;
+    /** Base URL path prepended to all entity and operation paths (e.g. `"/api/v1"`). */
     basePath: string;
+    /** Map of entity names to their CRUD definitions. */
     entities: TEntities;
+    /** Optional map of custom operation names to their definitions. */
     operations?: TOperations;
+    /** Strategy for serializing list parameters (filters, sort, pagination) into URL search params. */
+    queryBuilder?: QueryBuilder;
 }
+/**
+ * Provides structured query key generators for a single entity, following the
+ * query key factory pattern recommended by TanStack Query.
+ *
+ * Generated automatically by {@link deriveQueryKeys} and used by `@simplix-react/react`
+ * to manage cache granularity and invalidation.
+ *
+ * @example
+ * ```ts
+ * import { defineApi } from "@simplix-react/contract";
+ *
+ * const api = defineApi(config);
+ *
+ * api.queryKeys.task.all;              // ["project", "task"]
+ * api.queryKeys.task.lists();          // ["project", "task", "list"]
+ * api.queryKeys.task.list({ status: "open" }); // ["project", "task", "list", { status: "open" }]
+ * api.queryKeys.task.details();        // ["project", "task", "detail"]
+ * api.queryKeys.task.detail("abc");    // ["project", "task", "detail", "abc"]
+ * ```
+ *
+ * @see {@link deriveQueryKeys} for the factory function.
+ */
 interface QueryKeyFactory {
+    /** Root key matching all queries for this entity: `[domain, entity]`. */
     all: readonly unknown[];
+    /** Returns key matching all list queries: `[domain, entity, "list"]`. */
     lists: () => readonly unknown[];
+    /** Returns key matching a specific list query with parameters. */
     list: (params: Record<string, unknown>) => readonly unknown[];
+    /** Returns key matching all detail queries: `[domain, entity, "detail"]`. */
     details: () => readonly unknown[];
+    /** Returns key matching a specific detail query by ID. */
     detail: (id: string) => readonly unknown[];
 }
+/**
+ * Provides a type-safe CRUD client for a single entity, derived from its
+ * {@link EntityDefinition} schemas.
+ *
+ * All methods infer request/response types directly from the Zod schemas,
+ * ensuring compile-time safety without manual type annotations.
+ *
+ * @typeParam TSchema - Zod schema for the entity's response shape.
+ * @typeParam TCreate - Zod schema for the creation payload.
+ * @typeParam TUpdate - Zod schema for the update payload.
+ *
+ * @example
+ * ```ts
+ * import { defineApi } from "@simplix-react/contract";
+ *
+ * const api = defineApi(config);
+ *
+ * // All methods are fully typed based on entity schemas
+ * const tasks = await api.client.task.list();
+ * const task = await api.client.task.get("task-1");
+ * const created = await api.client.task.create({ title: "New task" });
+ * const updated = await api.client.task.update("task-1", { title: "Updated" });
+ * await api.client.task.delete("task-1");
+ * ```
+ *
+ * @see {@link deriveClient} for the factory function.
+ */
 interface EntityClient<TSchema extends z.ZodType, TCreate extends z.ZodType, TUpdate extends z.ZodType> {
-    list: (parentId?: string) => Promise<z.infer<TSchema>[]>;
+    /** Fetches a list of entities, optionally scoped by parent ID and/or list parameters. */
+    list: (parentIdOrParams?: string | ListParams, params?: ListParams) => Promise<z.infer<TSchema>[]>;
+    /** Fetches a single entity by its ID. */
     get: (id: string) => Promise<z.infer<TSchema>>;
+    /** Creates a new entity, optionally under a parent resource. */
     create: (parentIdOrDto: string | z.infer<TCreate>, dto?: z.infer<TCreate>) => Promise<z.infer<TSchema>>;
+    /** Partially updates an existing entity by ID. */
     update: (id: string, dto: z.infer<TUpdate>) => Promise<z.infer<TSchema>>;
+    /** Deletes an entity by its ID. */
     delete: (id: string) => Promise<void>;
 }
+/**
+ * Represents a customizable fetch function signature.
+ *
+ * Allows replacing the default HTTP client with a custom implementation
+ * (e.g. for authentication headers, retry logic, or testing).
+ *
+ * @typeParam T - The expected response type after deserialization.
+ *
+ * @see {@link defaultFetch} for the built-in implementation.
+ * @see {@link defineApi} where this is provided via `options.fetchFn`.
+ */
 type FetchFn = <T>(path: string, options?: RequestInit) => Promise<T>;
+/**
+ * Represents the fully constructed API contract returned by {@link defineApi}.
+ *
+ * Contains the original configuration, a type-safe HTTP client, and query key
+ * factories for all registered entities. This is the primary interface consumed
+ * by `@simplix-react/react` and `@simplix-react/mock`.
+ *
+ * @typeParam TEntities - Map of entity names to their definitions.
+ * @typeParam TOperations - Map of operation names to their definitions.
+ *
+ * @see {@link defineApi} for constructing this contract.
+ * @see {@link @simplix-react/react!deriveHooks | deriveHooks} for deriving React hooks.
+ * @see {@link @simplix-react/mock!deriveMockHandlers | deriveMockHandlers} for deriving mock handlers.
+ */
 interface ApiContract<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>>> {
+    /** The original contract configuration. */
     config: ApiContractConfig<TEntities, TOperations>;
+    /** Type-safe HTTP client with methods for each entity and operation. */
     client: {
         [K in keyof TEntities]: EntityClient<TEntities[K]["schema"], TEntities[K]["createSchema"], TEntities[K]["updateSchema"]>;
     } & {
         [K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer _TInput, infer TOutput> ? (...args: unknown[]) => Promise<z.infer<TOutput>> : never;
     };
+    /** Query key factories for cache management, one per entity. */
     queryKeys: {
         [K in keyof TEntities]: QueryKeyFactory;
     };
 }
+/** Shorthand for an entity definition with any Zod schema types. */
+type AnyEntityDef = EntityDefinition<z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny>;
+/** Shorthand for an operation definition with any Zod schema types. */
+type AnyOperationDef = OperationDefinition<z.ZodTypeAny, z.ZodTypeAny>;
 
+/**
+ * Creates a fully-typed API contract from an {@link ApiContractConfig}.
+ *
+ * Serves as the main entry point for `@simplix-react/contract`. Takes a
+ * declarative config of entities and operations, then derives a type-safe
+ * HTTP client and query key factories. The returned contract is consumed
+ * by `@simplix-react/react` for hooks and `@simplix-react/mock` for MSW handlers.
+ *
+ * @typeParam TEntities - Map of entity names to their {@link EntityDefinition}s.
+ * @typeParam TOperations - Map of operation names to their {@link OperationDefinition}s.
+ *
+ * @param config - The API contract configuration defining entities, operations, and shared settings.
+ * @param options - Optional settings for customizing the contract.
+ * @param options.fetchFn - Custom fetch function replacing the built-in {@link defaultFetch}.
+ * @returns An {@link ApiContract} containing `config`, `client`, and `queryKeys`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { defineApi, simpleQueryBuilder } from "@simplix-react/contract";
+ *
+ * const projectApi = defineApi({
+ *   domain: "project",
+ *   basePath: "/api/v1",
+ *   entities: {
+ *     task: {
+ *       path: "/tasks",
+ *       schema: z.object({ id: z.string(), title: z.string() }),
+ *       createSchema: z.object({ title: z.string() }),
+ *       updateSchema: z.object({ title: z.string().optional() }),
+ *     },
+ *   },
+ *   queryBuilder: simpleQueryBuilder,
+ * });
+ *
+ * // Type-safe client usage
+ * const tasks = await projectApi.client.task.list();
+ * const task = await projectApi.client.task.get("task-1");
+ *
+ * // Query keys for TanStack Query
+ * projectApi.queryKeys.task.all;       // ["project", "task"]
+ * projectApi.queryKeys.task.detail("task-1"); // ["project", "task", "detail", "task-1"]
+ * ```
+ *
+ * @see {@link ApiContractConfig} for the full config shape.
+ * @see {@link @simplix-react/react!deriveHooks | deriveHooks} for deriving React Query hooks.
+ * @see {@link @simplix-react/mock!deriveMockHandlers | deriveMockHandlers} for deriving MSW handlers.
+ */
 declare function defineApi<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>> = Record<string, never>>(config: ApiContractConfig<TEntities, TOperations>, options?: {
     fetchFn?: FetchFn;
 }): {
@@ -65,38 +477,221 @@ declare function defineApi<TEntities extends Record<string, EntityDefinition<any
     queryKeys: { [K in keyof TEntities]: QueryKeyFactory; };
 };
 
+/**
+ * Derives a type-safe HTTP client from an {@link ApiContractConfig}.
+ *
+ * Iterates over all entities and operations in the config and generates
+ * corresponding CRUD methods and operation functions. Each entity produces
+ * `list`, `get`, `create`, `update`, and `delete` methods. Each operation
+ * produces a callable function with positional path parameter arguments.
+ *
+ * Typically called internally by {@link defineApi} rather than used directly.
+ *
+ * @typeParam TEntities - Map of entity names to their definitions.
+ * @typeParam TOperations - Map of operation names to their definitions.
+ * @param config - The API contract configuration.
+ * @param fetchFn - Custom fetch function; defaults to {@link defaultFetch}.
+ * @returns A client object with typed methods for each entity and operation.
+ *
+ * @example
+ * ```ts
+ * import { deriveClient } from "@simplix-react/contract";
+ *
+ * const client = deriveClient(config);
+ * const tasks = await client.task.list();
+ * ```
+ *
+ * @see {@link defineApi} for the recommended high-level API.
+ */
 declare function deriveClient<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>>>(config: ApiContractConfig<TEntities, TOperations>, fetchFn?: FetchFn): Record<string, unknown>;
 
+/**
+ * Derives a set of {@link QueryKeyFactory} instances for all entities in a contract.
+ *
+ * Generates structured query keys following the factory pattern recommended
+ * by TanStack Query. Each entity receives keys scoped by `[domain, entityName]`,
+ * enabling granular cache invalidation (e.g. invalidate all task lists without
+ * affecting task details).
+ *
+ * Typically called internally by {@link defineApi} rather than used directly.
+ *
+ * @typeParam TEntities - Map of entity names to their definitions.
+ * @param config - Subset of the API contract config containing `domain` and `entities`.
+ * @returns A map of entity names to their {@link QueryKeyFactory} instances.
+ *
+ * @example
+ * ```ts
+ * import { deriveQueryKeys } from "@simplix-react/contract";
+ *
+ * const queryKeys = deriveQueryKeys({ domain: "project", entities: { task: taskEntity } });
+ *
+ * queryKeys.task.all;              // ["project", "task"]
+ * queryKeys.task.lists();          // ["project", "task", "list"]
+ * queryKeys.task.detail("abc");    // ["project", "task", "detail", "abc"]
+ * ```
+ *
+ * @see {@link defineApi} for the recommended high-level API.
+ * @see {@link QueryKeyFactory} for the generated key structure.
+ */
 declare function deriveQueryKeys<TEntities extends Record<string, EntityDefinition<any, any, any>>>(config: Pick<ApiContractConfig<TEntities>, "domain" | "entities">): {
     [K in keyof TEntities]: QueryKeyFactory;
 };
 
 /**
- * Build URL path with parameter substitution.
- * buildPath("/topologies/:topologyId/controllers", { topologyId: "abc" })
- * -> "/topologies/abc/controllers"
+ * Substitutes `:paramName` placeholders in a URL path template with actual values.
+ *
+ * Values are URI-encoded to ensure safe inclusion in URLs. Used internally by
+ * {@link deriveClient} for building operation URLs, and available as a public
+ * utility for custom URL construction.
+ *
+ * @param template - URL path template with `:paramName` placeholders.
+ * @param params - Map of parameter names to their string values.
+ * @returns The resolved URL path with all placeholders replaced.
+ *
+ * @example
+ * ```ts
+ * import { buildPath } from "@simplix-react/contract";
+ *
+ * buildPath("/projects/:projectId/tasks", { projectId: "abc" });
+ * // "/projects/abc/tasks"
+ *
+ * buildPath("/tasks/:taskId/assign", { taskId: "task-1" });
+ * // "/tasks/task-1/assign"
+ * ```
  */
 declare function buildPath(template: string, params?: Record<string, string>): string;
 
+/**
+ * Represents an HTTP error response from the API.
+ *
+ * Thrown by {@link defaultFetch} and the internal multipart/blob fetchers when
+ * the server responds with a non-2xx status code. Captures both the HTTP status
+ * and the raw response body for debugging.
+ *
+ * @example
+ * ```ts
+ * import { ApiError } from "@simplix-react/contract";
+ *
+ * try {
+ *   await api.client.task.get("nonexistent");
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.log(error.status); // 404
+ *     console.log(error.body);   // "Not Found"
+ *   }
+ * }
+ * ```
+ */
 declare class ApiError extends Error {
+    /** HTTP status code of the failed response. */
     readonly status: number;
+    /** Raw response body text. */
     readonly body: string;
-    constructor(status: number, body: string);
+    constructor(
+    /** HTTP status code of the failed response. */
+    status: number, 
+    /** Raw response body text. */
+    body: string);
 }
 /**
- * Default fetch function that unwraps { data: T } envelope.
+ * Performs an HTTP request with automatic JSON content-type headers and
+ * `{ data: T }` envelope unwrapping.
+ *
+ * Serves as the built-in fetch implementation used by {@link deriveClient}
+ * when no custom `fetchFn` is provided. Returns `undefined` for 204 No Content
+ * responses and throws {@link ApiError} for non-2xx status codes.
+ *
+ * @typeParam T - The expected deserialized response type.
+ * @param path - The full URL path to fetch.
+ * @param options - Standard `RequestInit` options forwarded to the native `fetch`.
+ * @returns The unwrapped response data.
+ * @throws {@link ApiError} When the response status is not OK.
+ *
+ * @example
+ * ```ts
+ * import { defineApi, defaultFetch } from "@simplix-react/contract";
+ *
+ * // Use as-is (default behavior)
+ * const api = defineApi(config);
+ *
+ * // Or provide a custom wrapper
+ * const api = defineApi(config, {
+ *   fetchFn: async (path, options) => {
+ *     // Add auth header, then delegate to defaultFetch
+ *     return defaultFetch(path, {
+ *       ...options,
+ *       headers: { ...options?.headers, Authorization: `Bearer ${token}` },
+ *     });
+ *   },
+ * });
+ * ```
  */
 declare function defaultFetch<T>(path: string, options?: RequestInit): Promise<T>;
 
 /**
- * Convert camelCase to kebab-case.
- * "doorReader" -> "door-reader"
+ * Converts a camelCase string to kebab-case.
+ *
+ * Used internally for transforming entity names into URL-friendly path segments.
+ *
+ * @param str - The camelCase string to convert.
+ * @returns The kebab-case equivalent.
+ *
+ * @example
+ * ```ts
+ * import { camelToKebab } from "@simplix-react/contract";
+ *
+ * camelToKebab("doorReader");  // "door-reader"
+ * camelToKebab("myEntity");    // "my-entity"
+ * ```
  */
 declare function camelToKebab(str: string): string;
 /**
- * Convert camelCase to snake_case.
- * "doorReader" -> "door_reader"
+ * Converts a camelCase string to snake_case.
+ *
+ * Also handles hyphenated and space-separated inputs by replacing them with
+ * underscores before lowercasing.
+ *
+ * @param str - The camelCase string to convert.
+ * @returns The snake_case equivalent.
+ *
+ * @example
+ * ```ts
+ * import { camelToSnake } from "@simplix-react/contract";
+ *
+ * camelToSnake("doorReader");  // "door_reader"
+ * camelToSnake("myEntity");    // "my_entity"
+ * camelToSnake("some-field");  // "some_field"
+ * ```
  */
 declare function camelToSnake(str: string): string;
 
-export { type ApiContract, type ApiContractConfig, ApiError, type EntityClient, type EntityDefinition, type EntityParent, type EntityQuery, type FetchFn, type HttpMethod, type OperationDefinition, type QueryKeyFactory, buildPath, camelToKebab, camelToSnake, defaultFetch, defineApi, deriveClient, deriveQueryKeys };
+/**
+ * Provides a straightforward {@link QueryBuilder} implementation for common REST APIs.
+ *
+ * Serializes filters as flat key-value pairs, sort as `field:direction` comma-separated
+ * values, and pagination as `page`/`limit` (offset) or `cursor`/`limit` (cursor-based).
+ *
+ * @example
+ * ```ts
+ * import { defineApi, simpleQueryBuilder } from "@simplix-react/contract";
+ *
+ * const api = defineApi({
+ *   domain: "project",
+ *   basePath: "/api/v1",
+ *   entities: { task: taskEntity },
+ *   queryBuilder: simpleQueryBuilder,
+ * });
+ *
+ * // Produces: /api/v1/tasks?status=pending&sort=name:asc&page=1&limit=10
+ * await api.client.task.list({
+ *   filters: { status: "pending" },
+ *   sort: { field: "name", direction: "asc" },
+ *   pagination: { type: "offset", page: 1, limit: 10 },
+ * });
+ * ```
+ *
+ * @see {@link QueryBuilder} for implementing custom serialization strategies.
+ */
+declare const simpleQueryBuilder: QueryBuilder;
+
+export { type AnyEntityDef, type AnyOperationDef, type ApiContract, type ApiContractConfig, ApiError, type EntityClient, type EntityDefinition, type EntityParent, type EntityQuery, type FetchFn, type HttpMethod, type ListParams, type OperationDefinition, type PageInfo, type PaginationParam, type QueryBuilder, type QueryKeyFactory, type SortParam, buildPath, camelToKebab, camelToSnake, defaultFetch, defineApi, deriveClient, deriveQueryKeys, simpleQueryBuilder };