@codexsploitx/schemaapi 1.1.12 → 1.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexsploitx/schemaapi",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "Type-safe API contracts (HTTP/WebSocket) with adapters, client and docs generator.",
   "main": "dist/schemaapi.cjs.js",
   "module": "dist/schemaapi.esm.js",

package/readme.md

@@ -1,291 +1,179 @@
 <div align="center">
 
-# SchemaApi
+# ⚡ SchemaApi
 
-**The Zod of APIs**  
-*Type-safe contracts. Runtime validation. Auto-generated docs.*
+### **The Contract-First API Standard for TypeScript**
 
-[![npm version](https://img.shields.io/npm/v/%40codexsploitx%2Fschemaapi?style=flat-square&color=blue)](https://www.npmjs.com/package/@codexsploitx/schemaapi)
-[![License](https://img.shields.io/npm/l/%40codexsploitx%2Fschemaapi?style=flat-square&color=green)](LICENSE)
-[![Tests](https://img.shields.io/github/actions/workflow/status/CodexSploitx/SchemaApi/test.yml?label=tests&style=flat-square)](https://github.com/CodexSploitx/SchemaApi/actions)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+<p align="center">
+  <a href="https://codexsploitx.github.io/SchemaApi/">Website</a> •
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-adapters">Adapters</a> •
+  <a href="#-documentation">Docs</a>
+</p>
 
-[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Adapters](#-adapters) • [Documentation](#-documentation)
+[![npm version](https://img.shields.io/npm/v/@codexsploitx/schemaapi?style=for-the-badge&color=7b2cbf)](https://www.npmjs.com/package/@codexsploitx/schemaapi)
+[![Downloads](https://img.shields.io/npm/dm/@codexsploitx/schemaapi?style=for-the-badge&color=00f5d4)](https://www.npmjs.com/package/@codexsploitx/schemaapi)
+[![License](https://img.shields.io/npm/l/@codexsploitx/schemaapi?style=for-the-badge&color=f72585)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
 
-</div>
+<br>
 
----
+**Build type-safe APIs at the speed of thought.**  
+Define your contract once. Generate Backend Controllers, Frontend SDKs, and Documentation instantly.
 
-## 🚀 Why SchemaApi?
+</div>
 
-**Your API is a contract.** But in most codebases, that contract is broken into pieces:
-- Validation logic in controllers.
-- Types in a `types.ts` file.
-- Documentation in a stale Swagger file.
-- Client SDKs handwritten (and buggy).
+---
 
-**SchemaApi** unifies everything into a **Single Source of Truth**. Define your contract once, and get everything else for free.
+## 🔮 The Future of API Development
 
-> "It doesn't replace your framework. It makes it invincible."
+**SchemaApi** isn't just a validation library. It's an **Architecture**.
 
----
+By defining a **Single Source of Truth** (Contract), you eliminate the disconnect between your Backend and Frontend.
 
-## ✨ Features
+### 🆚 The Old Way vs. The SchemaApi Way
 
-| Feature | Description |
+| ❌ Traditional | ✅ SchemaApi |
 | :--- | :--- |
-| **🛡️ End-to-End Type Safety** | Types flow from your server contract directly to your client SDK. No code generation required. |
-| **⚡ Runtime Validation** | Powered by **[Zod](https://zod.dev)**. Automatically validates params, query, body, and headers. |
-| **🔐 Built-in Security** | Define `roles` and `scopes` directly in your contract. RBAC made simple. |
-| **📚 Auto Documentation** | Generate beautiful, interactive HTML documentation that never drifts from code. |
-| **🔌 Framework Agnostic** | Works with Express, Next.js, Fastify, Remix, NestJS, and more. |
-| **📦 Zero-Config SDK** | Export a fully typed client that handles methods, paths, and errors for you. |
+| Write Controllers manually | **Auto-generated strict controllers** |
+| Write `types.ts` manually | **Types inferred from schema** |
+| Write Frontend Fetch calls | **Auto-generated Typed SDK** |
+| Update Swagger manually | **Auto-generated Documentation** |
+| "It works on my machine" | **"It adheres to the contract"** |
 
 ---
 
-## 📦 Installation
+## ✨ Superpowers
 
-### Core package
-
-```bash
-# npm
-npm install @codexsploitx/schemaapi zod
-
-# pnpm
-pnpm add @codexsploitx/schemaapi zod
-
-# yarn
-yarn add @codexsploitx/schemaapi zod
-```
+<div align="center">
 
-### Per-adapter setup
+| 🛡️ **End-to-End Type Safety** | ⚡ **Runtime Validation** | 🔌 **Adapter Agnostic** |
+| :--- | :--- | :--- |
+| Your Backend types **ARE** your Frontend types. Zero duplication. | Powered by **Zod**. If the data is wrong, the request never hits your logic. | Works with Express, Next.js, Fastify, NestJS, Remix, and more. |
 
-Below are the recommended commands for **new projects** and for **existing projects**.
+| 📦 **Zero-Config SDK** | 🚀 **Instant Mocking** | 📚 **Live Documentation** |
+| :--- | :--- | :--- |
+| Frontend devs get a fully typed client. `client.users.get({ id })` | Start frontend work before the backend is even written. | Beautiful HTML docs generated from your contracts. |
 
-#### CLI quick reference
+</div>
 
-| Adapter  | Init command                                      |
-|---------|----------------------------------------------------|
-| Express | `npx @codexsploitx/schemaapi init express`         |
-| Next.js | `npx @codexsploitx/schemaapi init next`            |
-| Fastify | `npx @codexsploitx/schemaapi init fastify`         |
-| Remix   | `npx @codexsploitx/schemaapi init remix`           |
-| NestJS  | `npx @codexsploitx/schemaapi init nest`            |
-| Deno    | `npx @codexsploitx/schemaapi init deno`            |
+---
 
-#### Express
+## 🚀 Quick Start
 
-- 🆕 **New project**
+Go from **Zero** to **Production-Ready API** in 30 seconds.
 
+### 1. Initialize
 ```bash
-mkdir my-express-api && cd my-express-api
-npm init -y
-npm install express @codexsploitx/schemaapi zod
 npx @codexsploitx/schemaapi init express
 ```
 
-- ♻️ **Existing Express project**
-
-```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init express
-```
-
-#### Next.js
-
-- 🆕 **New project**
-
-```bash
-npx create-next-app@latest my-next-api --ts
-cd my-next-api
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init next
-```
-
-- ♻️ **Existing Next.js project**
-
+### 2. Generate Resource
 ```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init next
+npx @codexsploitx/schemaapi generate resource users
 ```
 
-El comando `schemaapi init next` creará automáticamente:
-
-- Carpeta `contracts/` con un contrato de ejemplo `usersContract.ts`.
-- `contracts/index.ts` exportando los contratos.
-- `schemaapi.config.json` apuntando a `contracts/`.
-- Un handler de ejemplo compatible con **App Router** en `app/api/users/route.ts`.
-
-#### Fastify
-
-- 🆕 **New project**
-
+### 3. Generate SDK
 ```bash
-mkdir my-fastify-api && cd my-fastify-api
-npm init -y
-npm install fastify @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init fastify
+npx @codexsploitx/schemaapi generate sdk users
 ```
 
-- ♻️ **Existing Fastify project**
+**That's it.** You now have:
+- `contracts/usersContract.ts`: The definition.
+- `src/routes/users.ts`: The backend implementation.
+- `src/sdk/usersClient.ts`: The frontend client.
 
-```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init fastify
-```
-
-#### Remix
-
-- 🆕 **New project**
-
-```bash
-npx create-remix@latest
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init remix
-```
-
-- ♻️ **Existing Remix project**
-
-```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init remix
-
-#### NestJS
-
-- 🆕 **New project**
-
-```bash
-npm i -g @nestjs/cli
-nest new my-nest-api
-cd my-nest-api
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init nest
-```
-
-- ♻️ **Existing NestJS project**
-
-```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init nest
-```
-
-#### Deno
+---
 
-- 🆕 / ♻️ **Deno projects**
+## 🧩 The Ecosystem (Adapters)
 
-En Deno no se usa npm para el runtime, pero puedes usar SchemaApi en tu
-tooling o en proyectos que usen `deno2node`. Para Node+Deno híbrido:
+SchemaApi plays nice with everyone. Use the CLI to drop into any stack.
 
-```bash
-npm install @codexsploitx/schemaapi zod
-npx @codexsploitx/schemaapi init deno
-```
+| Stack | Status | CLI Command |
+| :--- | :---: | :--- |
+| <img src="https://simpleicons.org/icons/express.svg" width="18"/> **Express** | 🟢 Stable | `npx ... init express` |
+| <img src="https://simpleicons.org/icons/nextdotjs.svg" width="18"/> **Next.js** | 🟢 Stable | `npx ... init next` |
+| <img src="https://simpleicons.org/icons/fastify.svg" width="18"/> **Fastify** | 🟢 Stable | `npx ... init fastify` |
+| <img src="https://simpleicons.org/icons/remix.svg" width="18"/> **Remix** | 🟢 Stable | `npx ... init remix` |
+| <img src="https://simpleicons.org/icons/nestjs.svg" width="18"/> **NestJS** | 🟢 Stable | `npx ... init nest` |
+| <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/84/Deno.svg/1200px-Deno.svg.png" width="18"/> **Deno** | 🟢 Stable | `npx ... init deno` |
+| <img src="https://simpleicons.org/icons/nodedotjs.svg" width="18"/> **Koa/Hapi**| 🟡 Beta | `npx ... init koa` |
 
 ---
 
-## 🛠 Usage
-
-### 1️⃣ Define the Contract
+## 🛠️ Usage Example
 
-Create a shared file (e.g., `contract.ts`). This is your API's law.
+### 1️⃣ The Contract (`contracts/post.ts`)
+This is the **Law**.
 
 ```typescript
 import { createContract } from "@codexsploitx/schemaapi";
 import { z } from "zod";
 
-export const contract = createContract({
-  "/users/:id": {
-    GET: {
+export const postContract = createContract({
+  name: "posts",
+  routes: {
+    "GET /posts/:id": {
       params: z.object({ id: z.string().uuid() }),
-      response: z.object({
-        id: z.string(),
-        name: z.string(),
-        email: z.string().email(),
-      }),
-      errors: {
-        404: "USER_NOT_FOUND",
-      },
-    },
-  },
+      responses: {
+        200: z.object({ id: z.string(), title: z.string() }),
+        404: z.object({ error: z.string() })
+      }
+    }
+  }
 });
 ```
 
-### 2️⃣ Implement the Server
-
-Use the `handle` method to implement the logic. SchemaApi ensures you return exactly what the contract promises.
+### 2️⃣ The Backend (`src/routes/post.ts`)
+Implement the logic. Types are **enforced**.
 
 ```typescript
-import express from "express";
-import { contract } from "./contract";
-
-const app = express();
-
-app.get(
-  "/users/:id",
-  contract.handle("GET /users/:id", async ({ params }) => {
-    // `params.id` is strictly typed as a UUID string
-    const user = await db.users.find(params.id);
-
-    if (!user) {
-      throw { status: 404, message: "User not found" };
-    }
-
-    // TypeScript ensures this return value matches the contract
-    return user; 
-  })
-);
+// Express Adapter Example
+router.get("/posts/:id", async (req, res) => {
+  // `req.params.id` is strictly typed as string (UUID)
+  const post = await db.find(req.params.id);
+  
+  if (!post) return res.status(404).json({ error: "Not found" });
+  
+  // Return type is checked against contract
+  return res.json(post); 
+});
 ```
 
-### 3️⃣ Consume with Client SDK
-
-No more manual fetch calls. No more `any`.
+### 3️⃣ The Frontend (`src/app.ts`)
+Consume with the generated SDK.
 
 ```typescript
-import { createClient } from "@codexsploitx/schemaapi";
-import { contract } from "./shared/contract";
+import { PostClient } from "./sdk/postClient";
 
-const client = createClient(contract, { 
-  baseUrl: "https://api.example.com" 
-});
-
-// Full autocomplete & type checking
-const user = await client.users.get({ 
-  id: "550e8400-e29b-41d4-a716-446655440000" 
-});
+const client = new PostClient("https://api.myapp.com");
 
-console.log(user.email); // ✅ Typed!
+// ✨ Autocomplete heaven
+const post = await client.getPost({ id: "123-abc" });
+console.log(post.title);
 ```
 
 ---
 
-## 🔌 Adapters Ecosystem
+## 💻 CLI Commands
 
-SchemaApi is designed to drop into any stack.
+Your swiss-army knife for API development.
 
-| Adapter | Status | Package Support |
-| :--- | :---: | :--- |
-| <img src="https://raw.githubusercontent.com/expressjs/expressjs.com/gh-pages/images/favicon.png" width="20" /> **Express** | ✅ Stable | Native support |
-| <img src="https://assets.vercel.com/image/upload/v1662130559/nextjs/Icon_dark_background.png" width="20" /> **Next.js** | ✅ Stable | API Routes & App Router |
-| <img src="https://raw.githubusercontent.com/fastify/graphics/master/fastify-icon.png" width="20" /> **Fastify** | ✅ Stable | High performance |
-| <img src="https://github.com/remix-run/branding/raw/main/remix-r.png" width="20" /> **Remix** | ✅ Stable | Loaders & Actions |
-| <img src="https://nestjs.com/img/logo-small.svg" width="20" /> **NestJS** | ✅ Stable | Decorators |
-| <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/84/Deno.svg/1200px-Deno.svg.png" width="20" /> **Deno** | ✅ Stable | Native HTTP |
-| ⚡ **WebSocket** | 🚧 Beta | Real-time contracts |
+- `npx @codexsploitx/schemaapi init <stack>` -> Setup project
+- `npx @codexsploitx/schemaapi generate resource <name>` -> Create API route
+- `npx @codexsploitx/schemaapi generate sdk <name>` -> Create Typed Client
+- `npx @codexsploitx/schemaapi generate tests <name>` -> Create Integration Tests
+- `npx @codexsploitx/schemaapi generate docs` -> Build HTML Documentation website
+- `npx @codexsploitx/schemaapi audit` -> Check for security & best practices
 
 ---
 
-## 📚 Documentation Generator
-
-Stop writing Swagger files manually. Generate a stunning static documentation site with one command.
-
-```bash
-npx schemaapi generate docs --out ./docs
-```
-
-It creates a fully responsive, dark-mode ready HTML dashboard showing all your routes, schemas, and types.
+<div align="center">
 
----
+### Ready to build the future?
 
-## 📄 License
+[Get Started](https://codexsploitx.github.io/SchemaApi/)
 
 MIT © [CodexSploitx](https://github.com/CodexSploitx)
+
+</div>

package/website/docs.html

@@ -0,0 +1,183 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Documentation | SchemaApi</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+
+  <!-- Navigation -->
+  <nav class="container">
+    <a href="index.html" class="logo">
+      <span>⚡</span> SchemaApi
+    </a>
+    <div class="nav-links">
+      <a href="index.html">Home</a>
+      <a href="docs.html" class="active">Documentation</a>
+      <a href="https://github.com/codexsploitx/schemaapi">GitHub</a>
+    </div>
+  </nav>
+
+  <div class="container docs-layout">
+    <!-- Sidebar -->
+    <aside class="sidebar">
+      <ul>
+        <li><a href="#introduction" class="active">Introduction</a></li>
+        <li><a href="#installation">Installation</a></li>
+        <li><a href="#quick-start">Quick Start</a></li>
+        <li><a href="#cli-commands">CLI Commands</a></li>
+        <li><a href="#contracts">Contracts</a></li>
+        <li><a href="#sdk">Frontend SDK</a></li>
+        <li><a href="#testing">Testing</a></li>
+        <li><a href="#adapters">Adapters</a></li>
+      </ul>
+    </aside>
+
+    <!-- Content -->
+    <main class="docs-content">
+      <section id="introduction">
+        <h1>Documentation</h1>
+        <p>Welcome to SchemaApi. This guide will help you automate your backend and frontend development workflow using our contract-first approach.</p>
+      </section>
+
+      <section id="installation">
+        <h2>Installation</h2>
+        <p>You don't need to install SchemaApi globally. You can use it directly via <code>npx</code>, which ensures you're always using the latest version.</p>
+        <div class="code-block">
+          npx @codexsploitx/schemaapi init
+        </div>
+        <p>Or install it as a dev dependency in your project:</p>
+        <div class="code-block">
+          npm install -D @codexsploitx/schemaapi
+        </div>
+      </section>
+
+      <section id="quick-start">
+        <h2>Quick Start</h2>
+        <p>Get a full API up and running in less than a minute.</p>
+        
+        <p>1. Initialize your project:</p>
+        <div class="code-block">
+          <span class="cmd-text">npx</span> @codexsploitx/schemaapi init <span class="highlight">express</span>
+        </div>
+
+        <p>2. Generate a resource (e.g., users):</p>
+        <div class="code-block">
+          <span class="cmd-text">npx</span> @codexsploitx/schemaapi generate resource <span class="highlight">users</span>
+        </div>
+        <p>This creates:</p>
+        <ul>
+          <li><code>contracts/usersContract.ts</code> (The definition)</li>
+          <li><code>src/routes/users.ts</code> (The implementation)</li>
+        </ul>
+
+        <p>3. Generate the Client SDK:</p>
+        <div class="code-block">
+          <span class="cmd-text">npx</span> @codexsploitx/schemaapi generate sdk <span class="highlight">users</span>
+        </div>
+      </section>
+
+      <section id="cli-commands">
+        <h2>CLI Commands</h2>
+        <p>Here is the full list of available commands:</p>
+        
+        <h3>Init</h3>
+        <div class="code-block">npx @codexsploitx/schemaapi init &lt;framework&gt;</div>
+        <p>Supported frameworks: <code>express</code>, <code>fastify</code>, <code>next</code>, <code>nest</code>, <code>koa</code>, <code>hapi</code>, <code>remix</code>, <code>deno</code>.</p>
+
+        <h3>Generate Resource (Backend)</h3>
+        <div class="code-block">npx @codexsploitx/schemaapi generate resource &lt;name&gt;</div>
+        
+        <h3>Generate SDK (Frontend)</h3>
+        <div class="code-block">npx @codexsploitx/schemaapi generate sdk &lt;name&gt;</div>
+
+        <h3>Generate Tests</h3>
+        <div class="code-block">npx @codexsploitx/schemaapi generate tests &lt;name&gt;</div>
+
+        <h3>Generate Docs</h3>
+        <div class="code-block">npx @codexsploitx/schemaapi generate docs</div>
+      </section>
+
+      <section id="contracts">
+        <h2>Contracts</h2>
+        <p>Contracts are the heart of SchemaApi. They define the shape of your API. They are standard TypeScript files.</p>
+        <div class="code-block">
+<pre><span class="highlight">export</span> <span class="cmd-text">const</span> usersContract = {
+  name: "users",
+  routes: {
+    create: {
+      method: "POST",
+      path: "/users",
+      body: { name: "string", email: "string" },
+      responses: { 
+        201: { id: "string", name: "string" } 
+      }
+    }
+  }
+};</pre>
+        </div>
+      </section>
+
+      <section id="sdk">
+        <h2>Frontend SDK</h2>
+        <p>The generated SDK is a typed class that handles all HTTP communication.</p>
+        <div class="code-block">
+<pre><span class="highlight">import</span> { UsersClient } from "./sdk/usersClient";
+
+<span class="cmd-text">const</span> client = <span class="highlight">new</span> UsersClient("http://localhost:3000");
+
+<span class="comment">// Fully typed!</span>
+<span class="cmd-text">const</span> user = <span class="highlight">await</span> client.create({
+  name: "Alice",
+  email: "alice@example.com"
+});</pre>
+        </div>
+      </section>
+
+    </main>
+  </div>
+
+  <footer>
+    <div class="container">
+      <p>© 2026 SchemaApi. Documentation.</p>
+    </div>
+  </footer>
+
+  <script>
+    // Smooth scroll for anchor links is handled by CSS (scroll-behavior: smooth)
+    
+    // Active link highlighting on scroll (ScrollSpy)
+    const observerOptions = {
+      root: null,
+      rootMargin: '-20% 0px -70% 0px', // Trigger when section is near top
+      threshold: 0
+    };
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          // Remove active class from all links
+          document.querySelectorAll('.sidebar a').forEach(link => {
+            link.classList.remove('active');
+          });
+          
+          // Add active class to corresponding link
+          const id = entry.target.getAttribute('id');
+          const activeLink = document.querySelector(`.sidebar a[href="#${id}"]`);
+          if (activeLink) {
+            activeLink.classList.add('active');
+          }
+        }
+      });
+    }, observerOptions);
+
+    // Observe all sections
+    document.querySelectorAll('section[id]').forEach(section => {
+      observer.observe(section);
+    });
+  </script>
+
+</body>
+</html>