@simplix-react/contract 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+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[];
+}
+interface EntityClient<TSchema extends z.ZodType, TCreate extends z.ZodType, TUpdate extends z.ZodType> {
+    list: (parentId?: string) => Promise<z.infer<TSchema>[]>;
+    get: (id: string) => Promise<z.infer<TSchema>>;
+    create: (parentIdOrDto: string | z.infer<TCreate>, dto?: z.infer<TCreate>) => Promise<z.infer<TSchema>>;
+    update: (id: string, dto: z.infer<TUpdate>) => Promise<z.infer<TSchema>>;
+    delete: (id: string) => Promise<void>;
+}
+type FetchFn = <T>(path: string, options?: RequestInit) => Promise<T>;
+interface ApiContract<TEntities extends Record<string, EntityDefinition<any, any, any>>, TOperations extends Record<string, OperationDefinition<any, any>>> {
+    config: ApiContractConfig<TEntities, TOperations>;
+    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;
+    };
+    queryKeys: {
+        [K in keyof TEntities]: QueryKeyFactory;
+    };
+}
+
+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;
+}): {
+    config: ApiContractConfig<TEntities, TOperations>;
+    client: Record<string, unknown>;
+    queryKeys: { [K in keyof TEntities]: QueryKeyFactory; };
+};
+
+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>;
+
+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"
+ */
+declare function buildPath(template: string, params?: Record<string, string>): string;
+
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/**
+ * Default fetch function that unwraps { data: T } envelope.
+ */
+declare function defaultFetch<T>(path: string, options?: RequestInit): Promise<T>;
+
+/**
+ * Convert camelCase to kebab-case.
+ * "doorReader" -> "door-reader"
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Convert camelCase to snake_case.
+ * "doorReader" -> "door_reader"
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,148 @@
+// src/helpers/path-builder.ts
+function buildPath(template, params = {}) {
+  let result = template;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`:${key}`, encodeURIComponent(value));
+  }
+  return result;
+}
+
+// src/helpers/fetch.ts
+var ApiError = class extends Error {
+  constructor(status, body) {
+    super(`API Error ${status}: ${body}`);
+    this.status = status;
+    this.body = body;
+    this.name = "ApiError";
+  }
+};
+async function defaultFetch(path, options) {
+  const res = await fetch(path, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers
+    }
+  });
+  if (!res.ok) {
+    throw new ApiError(res.status, await res.text());
+  }
+  if (res.status === 204) {
+    return void 0;
+  }
+  const json = await res.json();
+  return json.data !== void 0 ? json.data : json;
+}
+
+// src/derive/client.ts
+function deriveClient(config, fetchFn = defaultFetch) {
+  const { basePath, entities, operations } = config;
+  const result = {};
+  for (const [name, entity] of Object.entries(entities)) {
+    result[name] = createEntityClient(basePath, entity, fetchFn);
+  }
+  if (operations) {
+    for (const [name, operation] of Object.entries(operations)) {
+      result[name] = createOperationClient(basePath, operation, fetchFn);
+    }
+  }
+  return result;
+}
+function createEntityClient(basePath, entity, fetchFn) {
+  const { path, parent } = entity;
+  return {
+    list(parentId) {
+      const url = parent && parentId ? `${basePath}${parent.path}/${parentId}${path}` : `${basePath}${path}`;
+      return fetchFn(url);
+    },
+    get(id) {
+      return fetchFn(`${basePath}${path}/${id}`);
+    },
+    create(parentIdOrDto, dto) {
+      if (parent && typeof parentIdOrDto === "string") {
+        const url2 = `${basePath}${parent.path}/${parentIdOrDto}${path}`;
+        return fetchFn(url2, {
+          method: "POST",
+          body: JSON.stringify(dto)
+        });
+      }
+      const url = `${basePath}${path}`;
+      return fetchFn(url, {
+        method: "POST",
+        body: JSON.stringify(parentIdOrDto)
+      });
+    },
+    update(id, dto) {
+      return fetchFn(`${basePath}${path}/${id}`, {
+        method: "PATCH",
+        body: JSON.stringify(dto)
+      });
+    },
+    delete(id) {
+      return fetchFn(`${basePath}${path}/${id}`, { method: "DELETE" });
+    }
+  };
+}
+function createOperationClient(basePath, operation, fetchFn) {
+  return (...args) => {
+    const pathParams = {};
+    const paramNames = (operation.path.match(/:(\w+)/g) ?? []).map(
+      (p) => p.slice(1)
+    );
+    let inputData = void 0;
+    let argIndex = 0;
+    for (const paramName of paramNames) {
+      if (argIndex < args.length) {
+        pathParams[paramName] = String(args[argIndex]);
+        argIndex++;
+      }
+    }
+    if (argIndex < args.length) {
+      inputData = args[argIndex];
+    }
+    const url = `${basePath}${buildPath(operation.path, pathParams)}`;
+    const options = { method: operation.method };
+    if (inputData !== void 0 && operation.method !== "GET") {
+      options.body = JSON.stringify(inputData);
+    }
+    return fetchFn(url, options);
+  };
+}
+
+// src/derive/query-keys.ts
+function deriveQueryKeys(config) {
+  const { domain, entities } = config;
+  const result = {};
+  for (const entityName of Object.keys(entities)) {
+    result[entityName] = createQueryKeyFactory(domain, entityName);
+  }
+  return result;
+}
+function createQueryKeyFactory(domain, entity) {
+  return {
+    all: [domain, entity],
+    lists: () => [domain, entity, "list"],
+    list: (params) => [domain, entity, "list", params],
+    details: () => [domain, entity, "detail"],
+    detail: (id) => [domain, entity, "detail", id]
+  };
+}
+
+// src/define-api.ts
+function defineApi(config, options) {
+  return {
+    config,
+    client: deriveClient(config, options?.fetchFn),
+    queryKeys: deriveQueryKeys(config)
+  };
+}
+
+// src/helpers/case-transform.ts
+function camelToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function camelToSnake(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+export { ApiError, buildPath, camelToKebab, camelToSnake, defaultFetch, defineApi, deriveClient, deriveQueryKeys };

package/dist/mcp-tools.d.ts

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,62 @@
+// 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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,54 @@
+// 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

@@ -0,0 +1,41 @@
+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 };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@simplix-react/contract",
+  "version": "0.0.1",
+  "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"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo"
+  },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@simplix-react/config-typescript": "workspace:*",
+    "eslint": "^9.39.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0",
+    "zod": "^4.0.0"
+  }
+}