@codexsploitx/schemaapi 1.0.0 → 1.0.1

package/src/docs.ts

@@ -1,535 +0,0 @@
-import type { ContractDocs, FieldDoc, MethodDoc } from "./core/contract";
-
-export type DocsFormat = "json" | "html" | "text";
-
-export type RenderHtmlOptions = {
-  title?: string;
-  theme?: "light" | "dark" | "auto";
-};
-
-export function renderDocsJSON(docs: ContractDocs): string {
-  return JSON.stringify(docs, null, 2);
-}
-
-export function renderDocsText(docs: ContractDocs): string {
-  const lines: string[] = [];
-
-  lines.push("SchemaApi Contract");
-  lines.push("================================");
-
-  docs.routes.forEach((route) => {
-    lines.push("");
-    lines.push(`${route.method} ${route.path}`);
-    lines.push("-".repeat((route.method + route.path).length + 1));
-
-    if (route.roles && route.roles.length > 0) {
-      lines.push(`roles: ${route.roles.join(", ")}`);
-    }
-
-    if (route.media) {
-      const mediaParts: string[] = [];
-      if (route.media.kind) {
-        mediaParts.push(`kind=${route.media.kind}`);
-      }
-      if (route.media.contentTypes && route.media.contentTypes.length > 0) {
-        mediaParts.push(`types=[${route.media.contentTypes.join(", ")}]`);
-      }
-      if (route.media.maxSize) {
-        mediaParts.push(`maxSize=${route.media.maxSize}`);
-      }
-      lines.push(`media: ${mediaParts.join(" ")}`);
-    }
-
-    const renderSection = (name: string, fields?: FieldDoc[]) => {
-      if (!fields || fields.length === 0) {
-        return;
-      }
-      lines.push(``);
-      lines.push(`${name}:`);
-      fields.forEach((f) => {
-        const flag = f.optional ? "optional" : "required";
-        const typeName = f.type ? f.type : "unknown";
-        lines.push(`  - ${f.name}: ${typeName} (${flag})`);
-      });
-    };
-
-    renderSection("params", route.params);
-    renderSection("query", route.query);
-    renderSection("body", route.body);
-    renderSection("headers", route.headers);
-
-    if (route.errors && route.errors.length > 0) {
-      lines.push("");
-      lines.push("errors:");
-      route.errors.forEach((e) => {
-        lines.push(`  - ${e.status}: ${e.code}`);
-      });
-    }
-  });
-
-  return lines.join("\n");
-}
-
-function getThemeBackground(theme: RenderHtmlOptions["theme"]): string {
-  if (theme === "dark") {
-    return "#020617";
-  }
-  if (theme === "light") {
-    return "#f9fafb";
-  }
-  return "#0b1120";
-}
-
-function getThemeForeground(theme: RenderHtmlOptions["theme"]): string {
-  if (theme === "dark") {
-    return "#e5e7eb";
-  }
-  if (theme === "light") {
-    return "#111827";
-  }
-  return "#e5e7eb";
-}
-
-export function renderDocsHTML(
-  docs: ContractDocs,
-  options?: RenderHtmlOptions
-): string {
-  const title = options?.title ?? "SchemaApi Docs";
-  const bg = getThemeBackground(options?.theme);
-  const fg = getThemeForeground(options?.theme);
-
-  const escape = (value: unknown): string => {
-    if (value === undefined || value === null) {
-      return "";
-    }
-    return String(value)
-      .replace(/&/g, "&")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/"/g, "&quot;");
-  };
-
-  const renderFieldsTable = (caption: string, fields?: FieldDoc[]): string => {
-    if (!fields || fields.length === 0) {
-      return "";
-    }
-    const rows = fields
-      .map((f) => {
-        const typeName = f.type ? f.type : "unknown";
-        const badge = f.optional ? "optional" : "required";
-        return `<tr>
-  <td class="field-name">${escape(f.name)}</td>
-  <td class="field-type">${escape(typeName)}</td>
-  <td class="field-badge ${badge}">${badge}</td>
-</tr>`;
-      })
-      .join("\n");
-
-    return `<section class="block">
-  <div class="block-title">${escape(caption)}</div>
-  <table class="fields">
-    <thead>
-      <tr>
-        <th>name</th>
-        <th>type</th>
-        <th>required</th>
-      </tr>
-    </thead>
-    <tbody>
-${rows}
-    </tbody>
-  </table>
-</section>`;
-  };
-
-  const renderRoute = (route: MethodDoc): string => {
-    const method = escape(route.method);
-    const path = escape(route.path);
-
-    const roles =
-      route.roles && route.roles.length > 0
-        ? `<div class="pill-group">
-${route.roles
-  .map(
-    (r) => `<span class="pill pill-role">role: ${escape(r)}</span>`
-  )
-  .join("\n")}
-</div>`
-        : "";
-
-    const media = route.media
-      ? (() => {
-          const parts: string[] = [];
-          if (route.media?.kind) {
-            parts.push(`kind=${escape(route.media.kind)}`);
-          }
-          if (route.media?.contentTypes && route.media.contentTypes.length) {
-            parts.push(
-              `types=[${route.media.contentTypes
-                .map((t) => escape(t))
-                .join(", ")}]`
-            );
-          }
-          if (route.media?.maxSize) {
-            parts.push(`maxSize=${escape(route.media.maxSize)}`);
-          }
-          return `<div class="pill-group">
-  <span class="pill pill-media">media ${parts.join(" · ")}</span>
-</div>`;
-        })()
-      : "";
-
-    const errors =
-      route.errors && route.errors.length > 0
-        ? `<section class="block">
-  <div class="block-title">errors</div>
-  <table class="fields">
-    <thead>
-      <tr>
-        <th>status</th>
-        <th>code</th>
-      </tr>
-    </thead>
-    <tbody>
-${route.errors
-  .map(
-    (e) => `<tr>
-  <td class="field-status">${escape(e.status)}</td>
-  <td class="field-error-code">${escape(e.code)}</td>
-</tr>`
-  )
-  .join("\n")}
-    </tbody>
-  </table>
-</section>`
-        : "";
-
-    const params = renderFieldsTable("params", route.params);
-    const query = renderFieldsTable("query", route.query);
-    const body = renderFieldsTable("body", route.body);
-    const headers = renderFieldsTable("headers", route.headers);
-
-    return `<article class="route-card route-${method.toLowerCase()}">
-  <header class="route-header">
-    <span class="method method-${method.toLowerCase()}">${method}</span>
-    <span class="path">${path}</span>
-  </header>
-  <div class="route-meta">
-    ${roles}
-    ${media}
-  </div>
-  <div class="route-content">
-    ${params}
-    ${query}
-    ${body}
-    ${headers}
-    ${errors}
-  </div>
-</article>`;
-  };
-
-  const routesHtml = docs.routes.map((r) => renderRoute(r)).join("\n");
-
-  return `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <title>${escape(title)}</title>
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <style>
-    :root {
-      --bg: ${bg};
-      --fg: ${fg};
-      --accent: #38bdf8;
-      --accent-soft: rgba(56, 189, 248, 0.12);
-      --card-bg: rgba(15, 23, 42, 0.9);
-      --border-subtle: rgba(148, 163, 184, 0.35);
-      --badge-get: #22c55e;
-      --badge-post: #3b82f6;
-      --badge-put: #eab308;
-      --badge-delete: #ef4444;
-      --badge-other: #a855f7;
-      --font-sans: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text",
-        "Inter", sans-serif;
-      --font-mono: ui-monospace, Menlo, Monaco, Consolas, "Liberation Mono",
-        "Courier New", monospace;
-    }
-
-    * {
-      box-sizing: border-box;
-    }
-
-    body {
-      margin: 0;
-      padding: 2.5rem 1.5rem 3rem;
-      background: radial-gradient(circle at top left, #0f172a 0, var(--bg) 45%),
-        radial-gradient(circle at bottom right, #020617 0, var(--bg) 55%);
-      color: var(--fg);
-      font-family: var(--font-sans);
-      -webkit-font-smoothing: antialiased;
-    }
-
-    .shell {
-      max-width: 1120px;
-      margin: 0 auto;
-    }
-
-    .masthead {
-      display: flex;
-      flex-direction: column;
-      gap: 0.75rem;
-      margin-bottom: 2rem;
-    }
-
-    .brand {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.5rem;
-      font-family: var(--font-mono);
-      font-size: 0.9rem;
-      letter-spacing: 0.12em;
-      text-transform: uppercase;
-      color: #9ca3af;
-    }
-
-    .brand-mark {
-      width: 0.65rem;
-      height: 0.65rem;
-      border-radius: 999px;
-      background: radial-gradient(circle at 30% 30%, #e5e7eb, #38bdf8);
-      box-shadow: 0 0 0 4px rgba(56, 189, 248, 0.2);
-    }
-
-    .title {
-      font-size: 1.9rem;
-      font-weight: 600;
-      letter-spacing: -0.03em;
-    }
-
-    .subtitle {
-      font-size: 0.95rem;
-      color: #9ca3af;
-      max-width: 520px;
-    }
-
-    .routes-grid {
-      display: grid;
-      grid-template-columns: minmax(0, 1fr);
-      gap: 1rem;
-    }
-
-    @media (min-width: 900px) {
-      .routes-grid {
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-      }
-    }
-
-    .route-card {
-      border-radius: 1rem;
-      padding: 1rem 1.1rem 1.1rem;
-      background: rgba(15, 23, 42, 0.92);
-      border: 1px solid var(--border-subtle);
-      box-shadow: 0 18px 55px rgba(15, 23, 42, 0.8);
-      display: flex;
-      flex-direction: column;
-      gap: 0.75rem;
-    }
-
-    .route-header {
-      display: flex;
-      align-items: center;
-      gap: 0.75rem;
-      font-family: var(--font-mono);
-      font-size: 0.85rem;
-      letter-spacing: 0.06em;
-      text-transform: uppercase;
-    }
-
-    .method {
-      padding: 0.15rem 0.55rem;
-      border-radius: 999px;
-      border: 1px solid rgba(148, 163, 184, 0.5);
-      background: rgba(15, 23, 42, 0.8);
-    }
-
-    .method-get {
-      border-color: rgba(34, 197, 94, 0.6);
-      color: #bbf7d0;
-      background: rgba(34, 197, 94, 0.08);
-    }
-
-    .method-post {
-      border-color: rgba(59, 130, 246, 0.6);
-      color: #bfdbfe;
-      background: rgba(59, 130, 246, 0.08);
-    }
-
-    .method-put {
-      border-color: rgba(234, 179, 8, 0.6);
-      color: #fef9c3;
-      background: rgba(234, 179, 8, 0.08);
-    }
-
-    .method-delete {
-      border-color: rgba(239, 68, 68, 0.6);
-      color: #fee2e2;
-      background: rgba(239, 68, 68, 0.08);
-    }
-
-    .method-patch {
-      border-color: rgba(168, 85, 247, 0.6);
-      color: #ede9fe;
-      background: rgba(168, 85, 247, 0.08);
-    }
-
-    .path {
-      padding: 0.1rem 0.65rem;
-      border-radius: 999px;
-      background: radial-gradient(circle at 0% 0%, #0f172a, #020617);
-      border: 1px solid rgba(148, 163, 184, 0.5);
-      color: #e5e7eb;
-    }
-
-    .route-meta {
-      display: flex;
-      flex-direction: column;
-      gap: 0.25rem;
-    }
-
-    .pill-group {
-      display: flex;
-      flex-wrap: wrap;
-      gap: 0.25rem;
-    }
-
-    .pill {
-      font-family: var(--font-mono);
-      font-size: 0.7rem;
-      padding: 0.1rem 0.45rem;
-      border-radius: 999px;
-      border: 1px solid rgba(148, 163, 184, 0.4);
-      background: rgba(15, 23, 42, 0.9);
-      color: #9ca3af;
-    }
-
-    .pill-role {
-      border-color: rgba(52, 211, 153, 0.5);
-      color: #a7f3d0;
-    }
-
-    .pill-media {
-      border-color: rgba(56, 189, 248, 0.6);
-      color: #bae6fd;
-      background: rgba(15, 23, 42, 0.9);
-    }
-
-    .route-content {
-      display: flex;
-      flex-direction: column;
-      gap: 0.6rem;
-      margin-top: 0.2rem;
-    }
-
-    .block {
-      border-radius: 0.75rem;
-      border: 1px solid rgba(31, 41, 55, 0.9);
-      background: radial-gradient(circle at top left, #020617, #020617);
-      padding: 0.6rem 0.7rem 0.55rem;
-    }
-
-    .block-title {
-      font-family: var(--font-mono);
-      font-size: 0.65rem;
-      letter-spacing: 0.2em;
-      text-transform: uppercase;
-      color: #6b7280;
-      margin-bottom: 0.35rem;
-    }
-
-    table.fields {
-      width: 100%;
-      border-collapse: collapse;
-      font-size: 0.8rem;
-      font-family: var(--font-mono);
-    }
-
-    table.fields th {
-      text-align: left;
-      font-weight: 500;
-      color: #9ca3af;
-      padding-bottom: 0.2rem;
-    }
-
-    table.fields td {
-      padding: 0.12rem 0;
-    }
-
-    .field-name {
-      color: #e5e7eb;
-    }
-
-    .field-type {
-      color: #a5b4fc;
-    }
-
-    .field-badge {
-      font-size: 0.7rem;
-      padding: 0 0.4rem;
-      border-radius: 999px;
-      border: 1px solid rgba(148, 163, 184, 0.4);
-      color: #9ca3af;
-    }
-
-    .field-badge.required {
-      border-color: rgba(248, 113, 113, 0.6);
-      color: #fecaca;
-    }
-
-    .field-badge.optional {
-      border-color: rgba(59, 130, 246, 0.6);
-      color: #bfdbfe;
-    }
-
-    .field-status {
-      color: #f97316;
-    }
-
-    .field-error-code {
-      color: #fca5a5;
-    }
-  </style>
-</head>
-<body>
-  <div class="shell">
-    <header class="masthead">
-      <div class="brand">
-        <span class="brand-mark"></span>
-        <span>SCHEMAAPI · CONTRACT DOCS</span>
-      </div>
-      <h1 class="title">${escape(title)}</h1>
-      <p class="subtitle">
-        Contratos de API descritos directamente desde el runtime. Sin Swagger, sin
-        YAML. Solo SchemaApi como única fuente de verdad.
-      </p>
-    </header>
-    <main class="routes-grid">
-${routesHtml}
-    </main>
-  </div>
-</body>
-</html>`;
-}
-
-export function renderDocs(
-  docs: ContractDocs,
-  options: { format: DocsFormat } & Partial<RenderHtmlOptions>
-): string {
-  if (options.format === "json") {
-    return renderDocsJSON(docs);
-  }
-  if (options.format === "html") {
-    return renderDocsHTML(docs, options);
-  }
-  return renderDocsText(docs);
-}
-

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from "./core/contract";
-export * from "./core/client";
-export { generateSDK } from "./sdk";
-export * as adapters from "./adapters";
-export * from "./docs";

package/src/playground.test.ts

@@ -1,98 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { z } from "zod";
-import { contract } from "./playground";
-import { createContract, SchemaApiError } from "./core/contract";
-
-describe("Playground Contract", () => {
-  it("should be defined", () => {
-    expect(contract).toBeDefined();
-    expect(contract.schema).toBeDefined();
-  });
-
-  it("should have the correct structure", () => {
-    type PlaygroundSchema = Record<
-      string,
-      {
-        GET?: {
-          roles?: string[];
-        };
-      }
-    >;
-    const schema = contract.schema as PlaygroundSchema;
-    const route = schema["/users/:id"];
-    expect(route).toBeDefined();
-    const getRoute = route.GET;
-    expect(getRoute).toBeDefined();
-    expect(getRoute?.roles ?? []).toContain("admin");
-  });
-
-  it("should fail if dynamic params in route are not declared in params schema", () => {
-    expect(() =>
-      createContract({
-        "/posts/:postId/comments/:id": {
-          GET: {
-            params: z.object({ postId: z.string() }),
-            response: z.object({ ok: z.boolean() }),
-          },
-        },
-      }).handle("GET /posts/:postId/comments/:id", async () => ({ ok: true }))
-    ).toThrow(
-      "Dynamic path param :id in /posts/:postId/comments/:id is not defined in params"
-    );
-  });
-
-  it("should allow handler errors with status codes defined in contract.errors", async () => {
-    const c = createContract({
-      "/users/:id": {
-        GET: {
-          params: z.object({ id: z.string().uuid() }),
-          response: z.object({ ok: z.boolean() }),
-          errors: {
-            404: "USER_NOT_FOUND",
-          },
-        },
-      },
-    });
-
-    const handler = c.handle("GET /users/:id", async () => {
-      throw new SchemaApiError(404, "Not Found");
-    });
-
-    await expect(
-      handler({ params: { id: "550e8400-e29b-41d4-a716-446655440000" } })
-    ).rejects.toMatchObject({ code: 404 });
-  });
-
-  it("should reject handler errors with status codes not defined in contract.errors", async () => {
-    const c = createContract({
-      "/users/:id": {
-        GET: {
-          params: z.object({ id: z.string().uuid() }),
-          response: z.object({ ok: z.boolean() }),
-          errors: {
-            404: "USER_NOT_FOUND",
-          },
-        },
-      },
-    });
-
-    const handler = c.handle("GET /users/:id", async () => {
-      throw new SchemaApiError(418, "Teapot");
-    });
-
-    await expect(
-      handler({ params: { id: "550e8400-e29b-41d4-a716-446655440000" } })
-    ).rejects.toThrow("418 is not defined in contract.errors");
-  });
-
-  it("should expose docs derived from the contract schema", () => {
-    const docs = contract.docs();
-    expect(docs.routes.length).toBeGreaterThan(0);
-    const userRoute = docs.routes.find(
-      (r) => r.path === "/users/:id" && r.method === "GET"
-    );
-    expect(userRoute).toBeDefined();
-    expect(userRoute?.roles).toContain("admin");
-    expect(userRoute?.params?.some((f) => f.name === "id")).toBe(true);
-  });
-});

package/src/playground.ts

@@ -1,13 +0,0 @@
-import { createContract } from "./index";
-import { z } from "zod";
-
-export const contract = createContract({
-  "/users/:id": {
-    GET: {
-      params: z.object({ id: z.string().uuid() }),
-      headers: z.object({ authorization: z.string() }),
-      roles: ["user", "admin"],
-      response: z.object({ id: z.string(), username: z.string() }),
-    },
-  },
-});

package/src/sdk.ts

@@ -1,17 +0,0 @@
-import { createClient } from "./core/client";
-
-type GenerateSDKOptions = {
-  baseUrl: string;
-  fetch?: typeof fetch;
-};
-
-export function generateSDK<TContract>(
-  contract: { schema: TContract },
-  options: GenerateSDKOptions
-) {
-  return createClient(contract, {
-    baseUrl: options.baseUrl,
-    fetch: options.fetch,
-  });
-}
-