@simplix-react/contract 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,309 @@
+# @simplix-react/contract
+
+Define type-safe API contracts with Zod schemas. A single contract drives your HTTP client, React Query hooks, and MSW mock handlers.
+
+## Installation
+
+```bash
+pnpm add @simplix-react/contract
+```
+
+**Peer dependency:** `zod >= 4.0.0`
+
+```bash
+pnpm add zod
+```
+
+## Quick Example
+
+```ts
+import { z } from "zod";
+import { defineApi, simpleQueryBuilder } from "@simplix-react/contract";
+
+// 1. Define your contract
+const projectApi = defineApi({
+  domain: "project",
+  basePath: "/api/v1",
+  entities: {
+    task: {
+      path: "/tasks",
+      schema: z.object({
+        id: z.string(),
+        title: z.string(),
+        status: z.enum(["open", "closed"]),
+      }),
+      createSchema: z.object({
+        title: z.string(),
+      }),
+      updateSchema: z.object({
+        title: z.string().optional(),
+        status: z.enum(["open", "closed"]).optional(),
+      }),
+    },
+  },
+  queryBuilder: simpleQueryBuilder,
+});
+
+// 2. Use the type-safe client
+const tasks = await projectApi.client.task.list();
+const task = await projectApi.client.task.get("task-1");
+const created = await projectApi.client.task.create({ title: "New task" });
+const updated = await projectApi.client.task.update("task-1", { status: "closed" });
+await projectApi.client.task.delete("task-1");
+
+// 3. Use query keys for cache management
+projectApi.queryKeys.task.all;                      // ["project", "task"]
+projectApi.queryKeys.task.lists();                   // ["project", "task", "list"]
+projectApi.queryKeys.task.list({ status: "open" });  // ["project", "task", "list", { status: "open" }]
+projectApi.queryKeys.task.detail("task-1");          // ["project", "task", "detail", "task-1"]
+```
+
+## API Overview
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `defineApi` | Function | Creates a contract with client and query keys from a config |
+| `deriveClient` | Function | Generates a type-safe HTTP client from a contract config |
+| `deriveQueryKeys` | Function | Generates TanStack Query key factories from a contract config |
+| `buildPath` | Function | Substitutes `:param` placeholders in URL templates |
+| `defaultFetch` | Function | Built-in fetch with JSON content-type and `{ data }` envelope unwrapping |
+| `ApiError` | Class | Error type for non-2xx HTTP responses |
+| `simpleQueryBuilder` | Object | Ready-made `QueryBuilder` for common REST query string patterns |
+| `camelToKebab` | Function | Converts camelCase to kebab-case |
+| `camelToSnake` | Function | Converts camelCase to snake_case |
+
+### Type Exports
+
+| Export | Description |
+| --- | --- |
+| `EntityDefinition` | Describes a CRUD entity with Zod schemas |
+| `EntityParent` | Parent resource for nested URL construction |
+| `EntityQuery` | Named query scope filtering by parent relationship |
+| `OperationDefinition` | Describes a custom non-CRUD API operation |
+| `HttpMethod` | Union of supported HTTP methods |
+| `ApiContractConfig` | Full configuration input for `defineApi` |
+| `ApiContract` | Return type of `defineApi` |
+| `EntityClient` | CRUD client interface for a single entity |
+| `QueryKeyFactory` | Structured query key generators for TanStack Query |
+| `FetchFn` | Custom fetch function signature |
+| `ListParams` | Filters, sort, and pagination parameters for list queries |
+| `SortParam` | Sort field and direction |
+| `PaginationParam` | Offset-based or cursor-based pagination |
+| `PageInfo` | Server-returned pagination metadata |
+| `QueryBuilder` | Interface for serializing list params to URL search params |
+
+## Key Concepts
+
+### Zod Schema → Type Inference
+
+Every contract type is inferred from Zod schemas at compile time. You define schemas once; TypeScript infers the rest:
+
+```ts
+import { z } from "zod";
+
+const taskSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.enum(["open", "closed"]),
+});
+
+// z.infer<typeof taskSchema> → { id: string; title: string; status: "open" | "closed" }
+```
+
+The framework uses these inferred types throughout the client, hooks, and mock handlers, so your API types are always in sync with validation logic.
+
+### EntityDefinition
+
+An `EntityDefinition` is the building block for CRUD resources. It bundles three schemas:
+
+- **`schema`** — The full entity shape returned by the API
+- **`createSchema`** — The payload required to create a new entity
+- **`updateSchema`** — The payload for partial updates
+
+```ts
+const taskEntity = {
+  path: "/tasks",
+  schema: taskSchema,
+  createSchema: z.object({ title: z.string() }),
+  updateSchema: z.object({ title: z.string().optional() }),
+};
+```
+
+This single definition drives `list`, `get`, `create`, `update`, and `delete` methods on the client.
+
+### OperationDefinition
+
+For endpoints that don't fit the CRUD pattern (file uploads, RPC-style calls, batch operations), use `OperationDefinition`:
+
+```ts
+import { z } from "zod";
+import { defineApi } from "@simplix-react/contract";
+
+const api = defineApi({
+  domain: "project",
+  basePath: "/api/v1",
+  entities: { task: taskEntity },
+  operations: {
+    assignTask: {
+      method: "POST",
+      path: "/tasks/:taskId/assign",
+      input: z.object({ userId: z.string() }),
+      output: z.object({ id: z.string(), assigneeId: z.string() }),
+    },
+    exportReport: {
+      method: "GET",
+      path: "/projects/:projectId/export",
+      input: z.object({}),
+      output: z.any(),
+      responseType: "blob",
+    },
+  },
+});
+
+// Path params are positional arguments, input is the last argument
+await api.client.assignTask("task-1", { userId: "user-42" });
+```
+
+### Nested Entities (Parent Relationships)
+
+Entities can declare a `parent` for nested URL construction:
+
+```ts
+const taskEntity = {
+  path: "/tasks",
+  schema: taskSchema,
+  createSchema: createTaskSchema,
+  updateSchema: updateTaskSchema,
+  parent: { param: "projectId", path: "/projects" },
+};
+
+// Client adjusts URLs based on parent
+await api.client.task.list("project-1");
+// GET /api/v1/projects/project-1/tasks
+
+await api.client.task.create("project-1", { title: "New task" });
+// POST /api/v1/projects/project-1/tasks
+```
+
+### Query Keys
+
+The contract automatically generates TanStack Query-compatible key factories with hierarchical structure:
+
+```
+task.all              → ["project", "task"]                          (broadest)
+task.lists()          → ["project", "task", "list"]
+task.list({ ... })    → ["project", "task", "list", { ... }]
+task.details()        → ["project", "task", "detail"]
+task.detail("id")     → ["project", "task", "detail", "id"]         (most specific)
+```
+
+Invalidating a broader key automatically invalidates all more-specific keys beneath it.
+
+## Guides
+
+### Custom Fetch Function
+
+Replace the built-in HTTP client with custom logic for authentication, logging, or retry:
+
+```ts
+import { defineApi, defaultFetch } from "@simplix-react/contract";
+
+const api = defineApi(config, {
+  fetchFn: async (path, options) => {
+    const token = await getAuthToken();
+    return defaultFetch(path, {
+      ...options,
+      headers: {
+        ...options?.headers,
+        Authorization: `Bearer ${token}`,
+      },
+    });
+  },
+});
+```
+
+### Custom Query Builder
+
+Implement the `QueryBuilder` interface to match your API's query string conventions:
+
+```ts
+import { defineApi } from "@simplix-react/contract";
+import type { QueryBuilder } from "@simplix-react/contract";
+
+const springQueryBuilder: QueryBuilder = {
+  buildSearchParams(params) {
+    const sp = new URLSearchParams();
+    if (params.pagination?.type === "offset") {
+      // Spring uses 0-based page indexing
+      sp.set("page", String(params.pagination.page - 1));
+      sp.set("size", String(params.pagination.limit));
+    }
+    if (params.sort) {
+      const sorts = Array.isArray(params.sort) ? params.sort : [params.sort];
+      for (const s of sorts) {
+        sp.append("sort", `${s.field},${s.direction}`);
+      }
+    }
+    return sp;
+  },
+};
+
+const api = defineApi({
+  domain: "project",
+  basePath: "/api/v1",
+  entities: { task: taskEntity },
+  queryBuilder: springQueryBuilder,
+});
+```
+
+### Multipart File Uploads
+
+Use `contentType: "multipart"` in an operation definition for file upload endpoints:
+
+```ts
+const api = defineApi({
+  domain: "project",
+  basePath: "/api/v1",
+  entities: {},
+  operations: {
+    uploadAvatar: {
+      method: "POST",
+      path: "/users/:userId/avatar",
+      input: z.object({ file: z.instanceof(File) }),
+      output: z.object({ url: z.string() }),
+      contentType: "multipart",
+    },
+  },
+});
+
+await api.client.uploadAvatar("user-1", { file: selectedFile });
+```
+
+### Error Handling
+
+All client methods throw `ApiError` for non-2xx responses:
+
+```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);   // Raw response body
+  }
+}
+```
+
+## Related Packages
+
+| Package | Description |
+| --- | --- |
+| `@simplix-react/react` | Derives React Query hooks from the contract |
+| `@simplix-react/mock` | Generates MSW handlers and PGlite repositories from the contract |
+| `@simplix-react/testing` | Test utilities built on top of the contract and mock packages |
+
+---
+
+**Next Step** → [`@simplix-react/react`](../react/README.md) — Turn your contract into React Query hooks.

package/dist/index.d.ts

@@ -1,62 +1,470 @@
 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;
     };
 }
 
+/**
+ * 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 +473,219 @@ 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.
+ *
+ * Used internally for transforming entity names into database-friendly column names.
+ *
+ * @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"
+ * ```
  */
 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 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 };

package/dist/index.js

@@ -36,10 +36,10 @@ async function defaultFetch(path, options) {
 
 // src/derive/client.ts
 function deriveClient(config, fetchFn = defaultFetch) {
-  const { basePath, entities, operations } = config;
+  const { basePath, entities, operations, queryBuilder } = config;
   const result = {};
   for (const [name, entity] of Object.entries(entities)) {
-    result[name] = createEntityClient(basePath, entity, fetchFn);
+    result[name] = createEntityClient(basePath, entity, fetchFn, queryBuilder);
   }
   if (operations) {
     for (const [name, operation] of Object.entries(operations)) {
@@ -48,11 +48,24 @@ function deriveClient(config, fetchFn = defaultFetch) {
   }
   return result;
 }
-function createEntityClient(basePath, entity, fetchFn) {
+function createEntityClient(basePath, entity, fetchFn, queryBuilder) {
   const { path, parent } = entity;
   return {
-    list(parentId) {
-      const url = parent && parentId ? `${basePath}${parent.path}/${parentId}${path}` : `${basePath}${path}`;
+    list(parentIdOrParams, params) {
+      let parentId;
+      let listParams;
+      if (typeof parentIdOrParams === "string") {
+        parentId = parentIdOrParams;
+        listParams = params;
+      } else {
+        listParams = parentIdOrParams;
+      }
+      let url = parent && parentId ? `${basePath}${parent.path}/${parentId}${path}` : `${basePath}${path}`;
+      if (listParams && queryBuilder) {
+        const sp = queryBuilder.buildSearchParams(listParams);
+        const qs = sp.toString();
+        if (qs) url += `?${qs}`;
+      }
       return fetchFn(url);
     },
     get(id) {
@@ -101,6 +114,12 @@ function createOperationClient(basePath, operation, fetchFn) {
       inputData = args[argIndex];
     }
     const url = `${basePath}${buildPath(operation.path, pathParams)}`;
+    if (operation.contentType === "multipart" && inputData !== void 0) {
+      return multipartFetch(url, operation.method, toFormData(inputData), operation.responseType);
+    }
+    if (operation.responseType === "blob") {
+      return blobFetch(url, operation.method, inputData);
+    }
     const options = { method: operation.method };
     if (inputData !== void 0 && operation.method !== "GET") {
       options.body = JSON.stringify(inputData);
@@ -108,6 +127,42 @@ function createOperationClient(basePath, operation, fetchFn) {
     return fetchFn(url, options);
   };
 }
+function toFormData(data) {
+  const formData = new FormData();
+  if (data && typeof data === "object") {
+    for (const [key, value] of Object.entries(data)) {
+      if (value instanceof File || value instanceof Blob) {
+        formData.append(key, value);
+      } else if (value !== void 0 && value !== null) {
+        formData.append(key, String(value));
+      }
+    }
+  }
+  return formData;
+}
+async function multipartFetch(url, method, formData, responseType) {
+  const res = await fetch(url, { method, body: formData });
+  if (!res.ok) {
+    throw new ApiError(res.status, await res.text());
+  }
+  if (responseType === "blob") {
+    return res.blob();
+  }
+  const json = await res.json();
+  return json.data !== void 0 ? json.data : json;
+}
+async function blobFetch(url, method, inputData) {
+  const options = { method };
+  if (inputData !== void 0 && method !== "GET") {
+    options.body = JSON.stringify(inputData);
+    options.headers = { "Content-Type": "application/json" };
+  }
+  const res = await fetch(url, options);
+  if (!res.ok) {
+    throw new ApiError(res.status, await res.text());
+  }
+  return res.blob();
+}
 
 // src/derive/query-keys.ts
 function deriveQueryKeys(config) {
@@ -145,4 +200,33 @@ function camelToSnake(str) {
   return str.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
 }
 
-export { ApiError, buildPath, camelToKebab, camelToSnake, defaultFetch, defineApi, deriveClient, deriveQueryKeys };
+// src/helpers/query-builders.ts
+var simpleQueryBuilder = {
+  buildSearchParams(params) {
+    const sp = new URLSearchParams();
+    if (params.filters) {
+      for (const [k, v] of Object.entries(params.filters)) {
+        if (v !== void 0 && v !== null) sp.set(k, String(v));
+      }
+    }
+    if (params.sort) {
+      const sorts = Array.isArray(params.sort) ? params.sort : [params.sort];
+      sp.set(
+        "sort",
+        sorts.map((s) => `${s.field}:${s.direction}`).join(",")
+      );
+    }
+    if (params.pagination) {
+      if (params.pagination.type === "offset") {
+        sp.set("page", String(params.pagination.page));
+        sp.set("limit", String(params.pagination.limit));
+      } else {
+        sp.set("cursor", params.pagination.cursor);
+        sp.set("limit", String(params.pagination.limit));
+      }
+    }
+    return sp;
+  }
+};
+
+export { ApiError, buildPath, camelToKebab, camelToSnake, defaultFetch, defineApi, deriveClient, deriveQueryKeys, simpleQueryBuilder };

package/package.json

@@ -1,23 +1,20 @@
 {
   "name": "@simplix-react/contract",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Define type-safe API contracts with Zod schemas",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    },
-    "./openapi": {
-      "types": "./dist/openapi.d.ts",
-      "import": "./dist/openapi.js"
-    },
-    "./mcp": {
-      "types": "./dist/mcp-tools.d.ts",
-      "import": "./dist/mcp-tools.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -30,6 +27,7 @@
     "zod": ">=4.0.0"
   },
   "devDependencies": {
+    "@simplix-react/config-eslint": "workspace:*",
     "@simplix-react/config-typescript": "workspace:*",
     "eslint": "^9.39.2",
     "tsup": "^8.5.1",

package/dist/mcp-tools.d.ts

@@ -1,14 +0,0 @@
-import { E as EntityDefinition, O as OperationDefinition, A as ApiContractConfig } from './types-tFXBXgJP.js';
-import 'zod';
-
-interface MCPToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-}
-/**
- * Derive MCP tool definitions from contract config.
- */
-declare function deriveMCPTools<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>>>(config: ApiContractConfig<TEntities, TOperations>): MCPToolDefinition[];
-
-export { type MCPToolDefinition, deriveMCPTools };

package/dist/mcp-tools.js

@@ -1,62 +0,0 @@
-// src/derive/mcp-tools.ts
-function deriveMCPTools(config) {
-  const tools = [];
-  for (const [name, entity] of Object.entries(config.entities)) {
-    const capitalName = name.charAt(0).toUpperCase() + name.slice(1);
-    tools.push(
-      {
-        name: `list${capitalName}s`,
-        description: `List all ${name} entities`,
-        inputSchema: entity.parent ? {
-          type: "object",
-          properties: { [entity.parent.param]: { type: "string" } },
-          required: [entity.parent.param]
-        } : { type: "object", properties: {} }
-      },
-      {
-        name: `get${capitalName}`,
-        description: `Get a single ${name} by ID`,
-        inputSchema: {
-          type: "object",
-          properties: { id: { type: "string" } },
-          required: ["id"]
-        }
-      },
-      {
-        name: `create${capitalName}`,
-        description: `Create a new ${name}`,
-        inputSchema: { type: "object", properties: {} }
-      },
-      {
-        name: `update${capitalName}`,
-        description: `Update an existing ${name}`,
-        inputSchema: {
-          type: "object",
-          properties: { id: { type: "string" } },
-          required: ["id"]
-        }
-      },
-      {
-        name: `delete${capitalName}`,
-        description: `Delete a ${name}`,
-        inputSchema: {
-          type: "object",
-          properties: { id: { type: "string" } },
-          required: ["id"]
-        }
-      }
-    );
-  }
-  if (config.operations) {
-    for (const [name, op] of Object.entries(config.operations)) {
-      tools.push({
-        name,
-        description: `${op.method} ${op.path}`,
-        inputSchema: { type: "object", properties: {} }
-      });
-    }
-  }
-  return tools;
-}
-
-export { deriveMCPTools };

package/dist/openapi.d.ts

@@ -1,21 +0,0 @@
-import { E as EntityDefinition, O as OperationDefinition, A as ApiContractConfig } from './types-tFXBXgJP.js';
-import 'zod';
-
-interface OpenAPISpec {
-    openapi: "3.1.0";
-    info: {
-        title: string;
-        version: string;
-    };
-    paths: Record<string, unknown>;
-}
-/**
- * Derive OpenAPI 3.1 specification from contract config.
- * Full implementation requires zod-to-json-schema.
- */
-declare function deriveOpenAPI<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>>>(config: ApiContractConfig<TEntities, TOperations>, options?: {
-    title?: string;
-    version?: string;
-}): OpenAPISpec;
-
-export { type OpenAPISpec, deriveOpenAPI };

package/dist/openapi.js

@@ -1,54 +0,0 @@
-// src/derive/openapi.ts
-function deriveOpenAPI(config, options) {
-  const title = options?.title ?? config.domain;
-  const version = options?.version ?? "0.1.0";
-  const paths = {};
-  for (const [name, entity] of Object.entries(config.entities)) {
-    const entityPath = entity.parent ? `${config.basePath}${entity.parent.path}/{${entity.parent.param}}${entity.path}` : `${config.basePath}${entity.path}`;
-    const capitalName = name.charAt(0).toUpperCase() + name.slice(1);
-    paths[entityPath] = {
-      get: {
-        summary: `List ${name}`,
-        operationId: `list${capitalName}`,
-        responses: { "200": { description: "Success" } }
-      },
-      post: {
-        summary: `Create ${name}`,
-        operationId: `create${capitalName}`,
-        responses: { "201": { description: "Created" } }
-      }
-    };
-    paths[`${config.basePath}${entity.path}/{id}`] = {
-      get: {
-        summary: `Get ${name}`,
-        operationId: `get${capitalName}`,
-        responses: { "200": { description: "Success" } }
-      },
-      patch: {
-        summary: `Update ${name}`,
-        operationId: `update${capitalName}`,
-        responses: { "200": { description: "Success" } }
-      },
-      delete: {
-        summary: `Delete ${name}`,
-        operationId: `delete${capitalName}`,
-        responses: { "204": { description: "Deleted" } }
-      }
-    };
-  }
-  if (config.operations) {
-    for (const [name, op] of Object.entries(config.operations)) {
-      const opPath = `${config.basePath}${op.path}`;
-      paths[opPath] = {
-        [op.method.toLowerCase()]: {
-          summary: name,
-          operationId: name,
-          responses: { "200": { description: "Success" } }
-        }
-      };
-    }
-  }
-  return { openapi: "3.1.0", info: { title, version }, paths };
-}
-
-export { deriveOpenAPI };

package/dist/types-tFXBXgJP.d.ts

@@ -1,41 +0,0 @@
-import { z } from 'zod';
-
-interface EntityParent {
-    param: string;
-    path: string;
-}
-interface EntityQuery {
-    parent: string;
-    param: string;
-}
-interface EntityDefinition<TSchema extends z.ZodType = z.ZodType, TCreate extends z.ZodType = z.ZodType, TUpdate extends z.ZodType = z.ZodType> {
-    path: string;
-    schema: TSchema;
-    createSchema: TCreate;
-    updateSchema: TUpdate;
-    parent?: EntityParent;
-    queries?: Record<string, EntityQuery>;
-}
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-interface OperationDefinition<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
-    method: HttpMethod;
-    path: string;
-    input: TInput;
-    output: TOutput;
-    invalidates?: (queryKeys: Record<string, QueryKeyFactory>, params: Record<string, string>) => readonly unknown[][];
-}
-interface ApiContractConfig<TEntities extends Record<string, EntityDefinition<any, any, any>> = Record<string, EntityDefinition>, TOperations extends Record<string, OperationDefinition<any, any>> = Record<string, OperationDefinition>> {
-    domain: string;
-    basePath: string;
-    entities: TEntities;
-    operations?: TOperations;
-}
-interface QueryKeyFactory {
-    all: readonly unknown[];
-    lists: () => readonly unknown[];
-    list: (params: Record<string, unknown>) => readonly unknown[];
-    details: () => readonly unknown[];
-    detail: (id: string) => readonly unknown[];
-}
-
-export type { ApiContractConfig as A, EntityDefinition as E, OperationDefinition as O };