@codexsploitx/schemaapi 1.0.0 → 1.0.1

package/src/core/contract.ts

@@ -1,534 +0,0 @@
-import { z, ZodObject, ZodTypeAny } from "zod";
-
-export class SchemaApiError extends Error {
-  constructor(
-    public code: number,
-    message: string
-  ) {
-    super(message);
-    this.name = "SchemaApiError";
-  }
-}
-
-type RequestContext = {
-  params?: unknown;
-  query?: unknown;
-  body?: unknown;
-  headers?: unknown;
-  user?: { role?: string };
-  [key: string]: unknown;
-};
-
-type MediaConfig = {
-  kind?: "upload" | "download";
-  contentTypes?: string[];
-  maxSize?: number;
-};
-
-export type NormalizedErrorPayload = {
-  error: string;
-  message: string;
-  status: number;
-};
-
-export function buildErrorPayload(error: unknown): NormalizedErrorPayload {
-  if (error instanceof SchemaApiError) {
-    return {
-      error: error.message,
-      message: error.message,
-      status: error.code,
-    };
-  }
-  const typedError = error as { message?: string; status?: number; code?: number };
-  const status =
-    typeof typedError.status === "number"
-      ? typedError.status
-      : typeof typedError.code === "number"
-        ? typedError.code
-        : 500;
-  const message =
-    typeof typedError.message === "string"
-      ? typedError.message
-      : "Internal Server Error";
-
-  return {
-    error: message,
-    message,
-    status,
-  };
-}
-
-type MethodDefinition = {
-  params?: ZodTypeAny;
-  query?: ZodTypeAny;
-  body?: ZodTypeAny;
-  headers?: ZodTypeAny;
-  roles?: string[];
-  response?: ZodTypeAny;
-  clientMessages?: ZodTypeAny;
-  serverMessages?: ZodTypeAny;
-  media?: MediaConfig;
-  errors?: Record<string, unknown>;
-  [key: string]: unknown;
-};
-
-type RouteDefinition = Record<string, MethodDefinition>;
-
-type ContractDefinition = Record<string, RouteDefinition>;
-
-type CompareResult = {
-  breakingChanges: string[];
-};
-
-export type FieldDoc = {
-  name: string;
-  type?: string;
-  optional: boolean;
-};
-
-export type MethodDoc = {
-  method: string;
-  path: string;
-  params?: FieldDoc[];
-  query?: FieldDoc[];
-  body?: FieldDoc[];
-  headers?: FieldDoc[];
-  roles?: string[];
-  errors?: { status: string; code: string }[];
-  media?: MediaConfig;
-};
-
-export type ContractDocs = {
-  routes: MethodDoc[];
-};
-
-function extractRouteParams(route: string): string[] {
-  return route
-    .split("/")
-    .filter((segment) => segment.startsWith(":"))
-    .map((segment) => segment.slice(1))
-    .filter((name) => name.length > 0);
-}
-
-function getBaseSchema(schema: ZodTypeAny): ZodTypeAny {
-  let current: ZodTypeAny = schema;
-  while (
-    (current as { _def?: { innerType?: ZodTypeAny } })._def &&
-    (current as { _def?: { innerType?: ZodTypeAny } })._def?.innerType
-  ) {
-    const def = (current as unknown as { _def: { innerType: ZodTypeAny } })._def;
-    current = def.innerType;
-  }
-  return current;
-}
-
-function getObjectShape(schema: unknown): Record<string, ZodTypeAny> | null {
-  if (!schema) {
-    return null;
-  }
-  const base = getBaseSchema(schema as ZodTypeAny);
-  if (base instanceof ZodObject) {
-    const objectSchema = base as ZodObject<Record<string, ZodTypeAny>>;
-    return objectSchema.shape;
-  }
-  return null;
-}
-
-function getTypeName(schema: ZodTypeAny): string | undefined {
-  const base = getBaseSchema(schema);
-  const def = base._def as unknown;
-  if (!def || typeof def !== "object") {
-    return undefined;
-  }
-  const record = def as Record<string, unknown>;
-  const value = record["typeName"] || record["type"];
-  if (typeof value === "string") {
-    return value;
-  }
-  return undefined;
-}
-
-function isOptional(schema: ZodTypeAny): boolean {
-    return schema.isOptional();
-}
-
-export function createContract<T extends ContractDefinition>(schema: T) {
-  const api = {
-    handle(endpoint: string, handler: (ctx: RequestContext) => unknown | Promise<unknown>) {
-      const [method, route] = endpoint.split(" ");
-      const routeSchema = (schema as ContractDefinition)[route];
-
-      if (!routeSchema) {
-        throw new SchemaApiError(404, `Route ${route} not defined in contract`);
-      }
-
-      const methodSchema = routeSchema[method];
-
-      if (!methodSchema) {
-        throw new SchemaApiError(
-          405,
-          `Method ${method} not defined for route ${route}`
-        );
-      }
-
-      const dynamicParams = extractRouteParams(route);
-      if (dynamicParams.length > 0) {
-        const paramsShape = getObjectShape(methodSchema.params);
-        if (!paramsShape) {
-          throw new Error(
-            `Route ${route} has dynamic params but no params schema is defined`
-          );
-        }
-        dynamicParams.forEach((name) => {
-          if (!(name in paramsShape)) {
-            throw new Error(
-              `Dynamic path param :${name} in ${route} is not defined in params`
-            );
-          }
-        });
-      }
-
-      return async (ctx: RequestContext) => {
-        const context = ctx;
-
-        const media = (methodSchema as { media?: MediaConfig }).media;
-        if (media && media.kind === "upload") {
-          const rawHeaders = (context.headers ??
-            {}) as Record<string, unknown>;
-          const headers: Record<string, string> = {};
-          Object.keys(rawHeaders).forEach((key) => {
-            const value = rawHeaders[key];
-            if (typeof value === "string") {
-              headers[key.toLowerCase()] = value;
-            }
-          });
-
-          const contentTypeHeader = headers["content-type"];
-          if (media.contentTypes && media.contentTypes.length > 0) {
-            const matches =
-              !!contentTypeHeader &&
-              media.contentTypes.some((expected) => {
-                if (expected.endsWith("/*")) {
-                  const prefix = expected.slice(0, -1);
-                  return contentTypeHeader.startsWith(prefix);
-                }
-                return (
-                  contentTypeHeader === expected ||
-                  contentTypeHeader.startsWith(`${expected};`)
-                );
-              });
-            if (!matches) {
-              throw new SchemaApiError(415, "Unsupported Media Type");
-            }
-          }
-
-          if (media.maxSize && media.maxSize > 0) {
-            const lengthHeader = headers["content-length"];
-            if (lengthHeader !== undefined) {
-              const parsed = Number(lengthHeader);
-              if (!Number.isNaN(parsed) && parsed > media.maxSize) {
-                throw new SchemaApiError(413, "Payload Too Large");
-              }
-            }
-          }
-        }
-
-        if (methodSchema.roles && methodSchema.roles.length > 0) {
-          const userRole = context.user?.role;
-          if (!userRole || !methodSchema.roles.includes(userRole)) {
-            throw new SchemaApiError(403, "Forbidden");
-          }
-        }
-
-        try {
-          if (methodSchema.params && context.params !== undefined) {
-            context.params = methodSchema.params.parse(context.params);
-          }
-          if (methodSchema.query && context.query !== undefined) {
-            context.query = methodSchema.query.parse(context.query);
-          }
-          if (methodSchema.body && context.body !== undefined) {
-            context.body = methodSchema.body.parse(context.body);
-          }
-          if (methodSchema.headers && context.headers !== undefined) {
-            context.headers = methodSchema.headers.parse(context.headers);
-          }
-        } catch (error) {
-          if (error instanceof z.ZodError) {
-            throw new SchemaApiError(
-              400,
-              `Validation Error: ${JSON.stringify(error.flatten())}`
-            );
-          }
-          throw error;
-        }
-
-        let result: unknown;
-
-        try {
-          result = await handler(context);
-        } catch (error) {
-          if (error instanceof SchemaApiError) {
-            const code = error.code;
-            const errorsConfig = (methodSchema.errors ??
-              {}) as Record<string, unknown>;
-            const allowedStatuses = Object.keys(errorsConfig);
-
-            if (code >= 400 && code !== 400 && code !== 500) {
-              if (!allowedStatuses.includes(String(code))) {
-                throw new SchemaApiError(
-                  code,
-                  `${code} is not defined in contract.errors`
-                );
-              }
-            }
-
-            throw error;
-          }
-
-          throw error;
-        }
-
-        if (methodSchema.response) {
-          try {
-            return methodSchema.response.parse(result);
-          } catch (error) {
-            if (error instanceof z.ZodError) {
-              throw new SchemaApiError(
-                500,
-                `Response Validation Error: ${JSON.stringify(error.flatten())}`
-              );
-            }
-            throw error;
-          }
-        }
-
-        return result;
-      };
-    },
-    compareWith(other: { schema: ContractDefinition }): CompareResult {
-      const breaking: string[] = [];
-      const oldSchema = other.schema as ContractDefinition;
-      const newSchema = schema as ContractDefinition;
-
-      Object.keys(oldSchema).forEach((route) => {
-        if (!(route in newSchema)) {
-          breaking.push(`Route removed: ${route}`);
-          return;
-        }
-
-        const oldRoute = oldSchema[route];
-        const newRoute = newSchema[route];
-
-        Object.keys(oldRoute).forEach((method) => {
-          const oldMethod = oldRoute[method];
-          const newMethod = newRoute[method];
-          const pathId = `${method} ${route}`;
-
-          if (!newMethod) {
-            breaking.push(`Method removed: ${pathId}`);
-            return;
-          }
-
-          // Check Response (Output)
-          const oldResponseShape = getObjectShape(oldMethod.response);
-          const newResponseShape = getObjectShape(newMethod.response);
-
-          if (oldResponseShape && newResponseShape) {
-            Object.keys(oldResponseShape).forEach((field) => {
-              if (!(field in newResponseShape)) {
-                breaking.push(`Response field removed: ${field} in ${pathId}`);
-                return;
-              }
-
-              const oldField = oldResponseShape[field];
-              const newField = newResponseShape[field];
-
-              const oldType = getTypeName(oldField);
-              const newType = getTypeName(newField);
-
-              if (oldType && newType && oldType !== newType) {
-                breaking.push(
-                  `Response field type changed: ${field} in ${pathId}`
-                );
-              }
-            });
-          }
-
-          // Check Request Body (Input)
-          const oldBodyShape = getObjectShape(oldMethod.body);
-          const newBodyShape = getObjectShape(newMethod.body);
-
-          if (newBodyShape) {
-             Object.keys(newBodyShape).forEach((field) => {
-                const newField = newBodyShape[field];
-                const oldField = oldBodyShape ? oldBodyShape[field] : undefined;
-
-                if (!oldField) {
-                   // New field added. Check if required.
-                   if (!newField.isOptional()) {
-                      breaking.push(`New required request body field: ${field} in ${pathId}`);
-                   }
-                } else {
-                   // Field exists in both. Check type change.
-                   const oldType = getTypeName(oldField);
-                   const newType = getTypeName(newField);
-                   if (oldType && newType && oldType !== newType) {
-                      breaking.push(`Request body field type changed: ${field} in ${pathId}`);
-                   }
-                   
-                   // Check if became required (was optional)
-                   if (oldField.isOptional() && !newField.isOptional()) {
-                      breaking.push(`Request body field became required: ${field} in ${pathId}`);
-                   }
-                }
-             });
-          }
-          
-          // Check Query Params (Input)
-          const oldQueryShape = getObjectShape(oldMethod.query);
-          const newQueryShape = getObjectShape(newMethod.query);
-          
-          if (newQueryShape) {
-             Object.keys(newQueryShape).forEach((field) => {
-                const newField = newQueryShape[field];
-                const oldField = oldQueryShape ? oldQueryShape[field] : undefined;
-                
-                if (!oldField) {
-                    if (!newField.isOptional()) {
-                        breaking.push(`New required query param: ${field} in ${pathId}`);
-                    }
-                } else {
-                    const oldType = getTypeName(oldField);
-                    const newType = getTypeName(newField);
-                    if (oldType && newType && oldType !== newType) {
-                        breaking.push(`Query param type changed: ${field} in ${pathId}`);
-                    }
-                }
-             });
-          }
-
-          // Check Path Params (Input)
-          const oldParamsShape = getObjectShape(oldMethod.params);
-          const newParamsShape = getObjectShape(newMethod.params);
-          
-          if (newParamsShape) {
-              Object.keys(newParamsShape).forEach((field) => {
-                  const newField = newParamsShape[field];
-                  const oldField = oldParamsShape ? oldParamsShape[field] : undefined;
-                  
-                  if (oldField) {
-                      const oldType = getTypeName(oldField);
-                      const newType = getTypeName(newField);
-                      if (oldType && newType && oldType !== newType) {
-                          breaking.push(`Path param type changed: ${field} in ${pathId}`);
-                      }
-                  }
-              });
-          }
-
-          const oldErrors = (oldMethod.errors ?? {}) as Record<
-            string,
-            unknown
-          >;
-          const newErrors = (newMethod.errors ?? {}) as Record<
-            string,
-            unknown
-          >;
-
-          Object.keys(oldErrors).forEach((status) => {
-            if (!(status in newErrors)) {
-              breaking.push(`Status code removed: ${status} in ${pathId}`);
-            } else {
-              const oldError = oldErrors[status];
-              const newError = newErrors[status];
-              if (oldError !== newError) {
-                breaking.push(
-                  `Error code changed for status ${status} in ${pathId}`
-                );
-              }
-            }
-          });
-
-          const oldRoles = (oldMethod.roles ?? []) as string[];
-          const newRoles = (newMethod.roles ?? []) as string[];
-          oldRoles.forEach((role) => {
-            if (!newRoles.includes(role)) {
-              breaking.push(`Role removed: ${role} in ${pathId}`);
-            }
-          });
-        });
-      });
-
-      return { breakingChanges: breaking };
-    },
-    docs(): ContractDocs {
-      const routesDocs: MethodDoc[] = [];
-      const current = schema as ContractDefinition;
-
-      Object.keys(current).forEach((route) => {
-        const routeDef = current[route];
-        Object.keys(routeDef).forEach((method) => {
-          const methodDef = routeDef[method];
-
-          const doc: MethodDoc = {
-            method,
-            path: route,
-            roles: methodDef.roles ? [...methodDef.roles] : undefined,
-            media: methodDef.media,
-            errors: methodDef.errors
-              ? Object.keys(methodDef.errors).map((status) => ({
-                  status,
-                  code: String(methodDef.errors?.[status]),
-                }))
-              : undefined,
-          };
-
-          const fillFields = (
-            source: ZodTypeAny | undefined,
-            assign: (fields: FieldDoc[]) => void
-          ) => {
-            if (!source) {
-              return;
-            }
-            const shape = getObjectShape(source);
-            if (!shape) {
-              return;
-            }
-            const fields: FieldDoc[] = Object.keys(shape).map((name) => {
-              const fieldSchema = shape[name];
-              const typeName = getTypeName(fieldSchema);
-              const optional = isOptional(fieldSchema);
-              return {
-                name,
-                type: typeName,
-                optional,
-              };
-            });
-            assign(fields);
-          };
-
-          fillFields(methodDef.params, (fields) => {
-            doc.params = fields;
-          });
-          fillFields(methodDef.query, (fields) => {
-            doc.query = fields;
-          });
-          fillFields(methodDef.body, (fields) => {
-            doc.body = fields;
-          });
-          fillFields(methodDef.headers, (fields) => {
-            doc.headers = fields;
-          });
-
-          routesDocs.push(doc);
-        });
-      });
-
-      return { routes: routesDocs };
-    },
-    schema,
-  };
-
-  return api;
-}

package/src/core/versioning.test.ts

@@ -1,174 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { z } from "zod";
-import { createContract } from "./contract";
-
-describe("Versioning - compareWith", () => {
-  it("should detect removed routes", () => {
-    const v1 = createContract({
-      "/users": {
-        GET: { response: z.object({ id: z.string() }) },
-      },
-    });
-    const v2 = createContract({});
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain("Route removed: /users");
-  });
-
-  it("should detect removed methods", () => {
-    const v1 = createContract({
-      "/users": {
-        GET: { response: z.object({ id: z.string() }) },
-        POST: { response: z.object({ id: z.string() }) },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        GET: { response: z.object({ id: z.string() }) },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain("Method removed: POST /users");
-  });
-
-  it("should detect removed response fields", () => {
-    const v1 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({
-            id: z.string(),
-            username: z.string(),
-          }),
-        },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({
-            id: z.string(),
-          }),
-        },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain(
-      "Response field removed: username in GET /users"
-    );
-  });
-
-  it("should detect changed response field types", () => {
-    const v1 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({
-            id: z.string(),
-          }),
-        },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({
-            id: z.number(),
-          }),
-        },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain(
-      "Response field type changed: id in GET /users"
-    );
-  });
-
-  it("should detect removed status codes", () => {
-    const v1 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({ id: z.string() }),
-          errors: {
-            404: "Not Found",
-            500: "Server Error",
-          },
-        },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        GET: {
-          response: z.object({ id: z.string() }),
-          errors: {
-            500: "Server Error",
-          },
-        },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain(
-      "Status code removed: 404 in GET /users"
-    );
-  });
-
-  // New tests for Request validations (currently expected to fail or need implementation)
-  it("should detect changed request body field types", () => {
-    const v1 = createContract({
-      "/users": {
-        POST: {
-          body: z.object({
-            age: z.string(),
-          }),
-          response: z.object({ id: z.string() }),
-        },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        POST: {
-          body: z.object({
-            age: z.number(),
-          }),
-          response: z.object({ id: z.string() }),
-        },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain(
-      "Request body field type changed: age in POST /users"
-    );
-  });
-
-  it("should detect new required fields in request body", () => {
-    const v1 = createContract({
-      "/users": {
-        POST: {
-          body: z.object({
-            name: z.string(),
-          }),
-          response: z.object({ id: z.string() }),
-        },
-      },
-    });
-    const v2 = createContract({
-      "/users": {
-        POST: {
-          body: z.object({
-            name: z.string(),
-            age: z.number(), // New required field
-          }),
-          response: z.object({ id: z.string() }),
-        },
-      },
-    });
-
-    const result = v2.compareWith(v1);
-    expect(result.breakingChanges).toContain(
-      "New required request body field: age in POST /users"
-    );
-  });
-});