restix 0.0.1 → 0.0.3

package/README.md

@@ -1,61 +1,68 @@
 # restix
 
 **restix** is a strict, type-safe HTTP client builder designed for **CLI tools and backend applications**.
-It lets you define your API **once** as a contract (routes + mappings) and then make requests without rewriting fetch logic, URL building, or manual payload handling.
 
-The goal is simple:
+It allows you to define your API **once** as a contract and interact with it safely without rewriting fetch logic, URL builders, or request payload handling.
 
-> **Design your API → map it → call it safely**
+> Design your API → map it → call it safely
 
-No runtime magic, no hidden abstractions, no guessing.
+No runtime magic.
+No hidden abstractions.
+No guessing.
 
 ---
 
 ## Why restix?
 
 When building CLI tools or backend services, you often need to:
+
 - Call many HTTP endpoints
-- Inject params, query strings, headers, and body data
+- Inject URL params, query strings, headers, and body data
 - Keep everything type-safe
-- Avoid rewriting request logic over and over
+- Avoid request boilerplate
 
 **restix solves this by:**
+
 - Enforcing **exact input types** per endpoint
 - Preventing extra or missing fields at compile time
-- Automatically injecting params, query, body, and headers
-- Keeping request logic centralized and reusable
+- Supporting multiple injection strategies
+- Centralizing request logic
+- Staying minimal and predictable
 
 ---
 
 ## Core Concepts
 
-### 1. API Interface (Contract)
+### 1. API Contract (Type First)
 
-You define your API as a **TypeScript interface**.
-Each key represents a route, and its value represents the **exact data shape** allowed.
+Your API is defined as a TypeScript interface.
+Each key represents an endpoint, and its value represents the **exact allowed input**.
 
 ```ts
 interface API_INTERFACE {
-  'GET /users/{id}': {
-    id: string
+  'GET /packages/cli/name/{name}': {
+    name: string
   }
 
-  'POST /users/create': {
+  'POST /packages/cli/create': {
     name: string
-    email: string
+    version: string
+    developer: string
   }
 }
 ````
 
-This interface becomes the **single source of truth**.
+This interface is the **single source of truth**.
 
 ---
 
 ### 2. API Mapping
 
-Each endpoint must be mapped to explain **where data goes**:
+Each endpoint must declare how its data is injected.
+
+Supported injection targets:
 
-* `params` → URL params
+* `params` → URL parameters
 * `query` → query string
 * `body` → request body
 * `headers` → request headers
@@ -64,19 +71,15 @@ Each endpoint must be mapped to explain **where data goes**:
 import { apiMap, type API_MAPS, type GET_API } from 'restix'
 
 const api_maps: API_MAPS<API_INTERFACE> = {
-  'GET /users/{id}': {
-    map: apiMap<GET_API<API_INTERFACE, 'GET /users/{id}'>>({
-      params: ['id']
+  'GET /packages/cli/name/{name}': {
+    map: apiMap<GET_API<API_INTERFACE, 'GET /packages/cli/name/{name}'>>({
+      params: ['name']
     }),
-    res: 'json',
-    status: {
-      safe: 200,
-      404: () => 'User not found'
-    }
+    res: 'json'
   },
 
-  'POST /users/create': {
-    map: apiMap<GET_API<API_INTERFACE, 'POST /users/create'>>({
+  'POST /packages/cli/create': {
+    map: apiMap<GET_API<API_INTERFACE, 'POST /packages/cli/create'>>({
       body: ['*']
     }),
     res: 'json',
@@ -87,75 +90,150 @@ const api_maps: API_MAPS<API_INTERFACE> = {
 }
 ```
 
-* `'*'` means **all fields**
-* Explicit keys mean **only those fields**
+`'*'` means **all fields**
+Explicit keys mean **only those fields**
+
+---
+
+### 3. Query Injection Strategies
+
+#### A) Automatic Query Injection
+
+```ts
+map: apiMap({
+  query: ['q', 'v']
+})
+```
+
+```ts
+api.request('GET /search', {
+  q: 'nex',
+  v: '1'
+})
+```
+
+➡️ `?q=nex&v=1`
+
+---
+
+#### B) URL-Positioned Query Injection
+
+```ts
+'GET /packages/cli/search?selam={v}&VERSION={v}'
+```
+
+```ts
+api.request(
+  'GET /packages/cli/search?selam={v}&VERSION={v}',
+  {
+    q: 'nex',
+    v: 'sa'
+  }
+)
+```
+
+➡️ `?selam=sa&VERSION=sa`
+
+This is especially useful for:
+
+* Legacy APIs
+* Fixed query naming conventions
+* Enterprise-style endpoints
 
 ---
 
-### 3. Creating the Client
+### 4. Creating the Client
 
 ```ts
 import { NexAPI } from 'restix'
 
 const api = new NexAPI<API_INTERFACE>(
-  'https://api.example.com',
+  'http://localhost:5000',
   api_maps
 )
 ```
 
-You can also provide **default injected data** (headers, query, body, params):
+#### With Defaults
 
 ```ts
 const api = new NexAPI<API_INTERFACE>(
-  'https://api.example.com',
+  'http://localhost:5000',
   api_maps,
   {
     headers: {
-      authorization: 'Bearer TOKEN'
+      'User-Agent': 'restix-cli'
+    },
+    status: {
+      404: () => 'Global not found'
     }
   }
 )
 ```
 
+Defaults are **merged**, not replaced.
+
 ---
 
-### 4. Making Requests (Type-Safe)
+### 5. Making Requests (Type-Safe)
 
 ```ts
-await api.request('GET /users/{id}', {
-  id: '123'
+await api.request('GET /packages/cli/name/{name}', {
+  name: 'xnex'
 })
 ```
 
 ```ts
-await api.request('POST /users/create', {
-  name: 'John',
-  email: 'john@example.com'
+await api.request('POST /packages/cli/create', {
+  name: 'xnex',
+  version: '0.0.1',
+  developer: 'Signor P'
 })
 ```
 
-❌ This will **fail at compile time**:
+❌ Compile-time error (extra field):
 
 ```ts
-api.request('POST /users/create', {
-  name: 'John',
-  email: 'john@example.com',
-  extra: 'not allowed'
+api.request('GET /packages/cli/name/{name}', {
+  name: 'xnex',
+  extra: 'nope'
 })
 ```
 
-Because **restix enforces exact types**.
+❌ Compile-time error (missing field):
+
+```ts
+api.request('POST /packages/cli/create', {
+  name: 'xnex'
+})
+```
+
+---
+
+## Status Handling
+
+Each endpoint can define status handlers:
+
+```ts
+status: {
+  safe: 200,
+  404: () => 'Not found',
+  400: () => 'Bad request'
+}
+```
+
+You can also define **global status defaults** when creating the client.
 
 ---
 
 ## Key Features
 
-* ✅ Exact object validation (no extra keys)
+* ✅ Exact object typing (no extra keys)
 * ✅ Route-based type inference
-* ✅ Automatic URL param injection
-* ✅ Automatic query string building
-* ✅ Automatic body & header extraction
-* ✅ CLI-friendly (works perfectly with Bun / Node)
+* ✅ URL param injection
+* ✅ Automatic & positional query injection
+* ✅ Header & body extraction
+* ✅ Global + local status handling
+* ✅ CLI-friendly (Bun / Node)
 * ✅ No runtime dependencies
 * ✅ No decorators, no reflection
 
@@ -165,12 +243,12 @@ Because **restix enforces exact types**.
 
 * CLI tools
 * Backend services
-* Internal tooling
 * Automation scripts
-* API SDKs
-* Monorepo shared clients
+* Internal SDKs
+* API clients
+* Monorepo shared tooling
 
-**Not** designed for browser-heavy frontend frameworks.
+Not designed for heavy frontend frameworks.
 
 ---
 
@@ -181,7 +259,7 @@ restix follows a **contract-first** approach:
 * Types are the contract
 * Mapping defines behavior
 * Requests are deterministic
-* Errors are caught at compile time, not runtime
+* Errors are caught at compile time
 
 If TypeScript allows it, restix allows it.
 If TypeScript rejects it, restix rejects it too.
@@ -190,10 +268,10 @@ If TypeScript rejects it, restix rejects it too.
 
 ## Status
 
-This package is **actively evolving**.
+This project is actively evolving.
 The API is intentionally minimal and strict.
 
-Contributions, ideas, and feedback are welcome.
+Ideas, issues, and contributions are welcome.
 
 ---
 

package/api.d.ts

@@ -8,6 +8,10 @@ export declare class NexAPI<API_INTERFACE extends {
         params?: Record<string, string>;
         query?: Record<string, string>;
         headers?: Record<string, string>;
+        status?: {
+            safe?: number;
+            [n: number]: (res: Response) => any;
+        };
     });
     request<URL extends (keyof API_INTERFACE) & string>(prefix: URL, data: Exact<API_INTERFACE[URL], API_INTERFACE[URL]>): Promise<any>;
 }

package/api.js

@@ -1,16 +1,42 @@
+import { Status } from './status';
 export class NexAPI {
     #base = 'http://localhost:5000';
     #api_maps;
-    #defaults;
+    #defaults = {
+        headers: { 'X-Client-Signature': 'restix/0.0.2 (by SignorP)' },
+        status: {
+            safe: Status.OK(undefined).status,
+            201: Status.CREATED,
+            202: Status.ACCEPTED,
+            204: Status.NO_CONTENT,
+            400: () => Status.BAD_REQUEST('Invalid request data', 'Check required parameters'),
+            401: () => Status.UNAUTHORIZED('Authentication required'),
+            403: () => Status.FORBIDDEN(),
+            404: () => Status.NOT_FOUND(),
+            405: () => Status.METHOD_NOT_ALLOWED(),
+            408: () => Status.REQUEST_TIMEOUT(),
+            409: () => Status.CONFLICT(),
+            413: () => Status.PAYLOAD_TOO_LARGE(),
+            415: () => Status.UNSUPPORTED_MEDIA_TYPE(),
+            422: () => Status.UNPROCESSABLE_ENTITY('Validation failed'),
+            429: () => Status.TOO_MANY_REQUESTS('Rate limit exceeded', 'Try again later'),
+            500: () => Status.INTERNAL_ERROR(),
+            501: () => Status.NOT_IMPLEMENTED(),
+            502: () => Status.BAD_GATEWAY(),
+            503: () => Status.SERVICE_UNAVAILABLE(),
+            504: () => Status.GATEWAY_TIMEOUT()
+        }
+    };
     constructor(base, api_maps, defaults) {
         this.#base = base;
         this.#api_maps = api_maps;
-        this.#defaults = defaults ?? {};
+        this.#defaults = { ...defaults, headers: { ...defaults?.headers ?? {}, ...this.#defaults.headers }, status: { ...this.#defaults.status, ...defaults?.status ?? {} } };
     }
     async request(prefix, data) {
         const api = this.#api_maps[prefix];
         if (!api)
             return;
+        api.status = { ...this.#defaults.status, ...(api.status ?? {}) };
         data = {
             ...data,
             ...this.#defaults.body ?? {},
@@ -32,16 +58,17 @@ export class NexAPI {
             url = this.#injectUrlData(url, api.map.params, data);
         if (api.map.query.length > 0)
             url = this.#injectQuery(url, api.map.query, data);
-        if (api.map.body.length > 0)
+        if (api.map.body.length > 0) {
             fetchOptoin.body = JSON.stringify(this.#injectData(api.map.body, data));
+            fetchOptoin.headers = { 'Content-type': 'application/json' };
+        }
         if (api.map.headers.length > 0)
-            fetchOptoin.headers = this.#injectData(api.map.headers, data);
-        console.log(url, method, { ...fetchOptoin });
+            fetchOptoin.headers = { ...this.#injectData(api.map.headers, data), ...(fetchOptoin.headers ?? {}) };
         const res = await fetch(url, fetchOptoin);
         if (res.status === api.status.safe)
             return await res[api.res]();
         else if (api.status && api.status[res.status])
-            return api.status[res.status]?.();
+            return await api.status[res.status]?.(res);
         return undefined;
     }
     #injectUrlData(url, params, data) {
@@ -50,13 +77,22 @@ export class NexAPI {
         return url;
     }
     #injectQuery(url, queries, data) {
-        for (const [i, query] of queries.entries()) {
-            if (i == 0)
-                url = `${url}?${query}=${data[query]}`;
-            else
-                url = `${url}&${query}=${data[query]}`;
+        for (const query of queries[0] == '*' ? Object.keys(data) : queries) {
+            if (!data[query])
+                continue;
+            const key = `={${query}}`;
+            if (url.includes(key)) {
+                url = url.replaceAll(key, `=${data[query]}`);
+                continue;
+            }
+            if (!url.includes('?'))
+                url = `${url}?${query}=${data[query]}&`;
+            else if (!url.endsWith('&'))
+                url = `${url}&${query}=${data[query]}&`;
+            else if (url.endsWith('&'))
+                url = `${url}${query}=${data[query]}&`;
         }
-        return url;
+        return url.endsWith('&') ? url.slice(0, url.length - 1) : url;
     }
     #injectData(body, data) {
         const res = {};

package/api.ts

@@ -1,30 +1,73 @@
-import type { API_MAPS, Exact } from './types'
+import { Status } from './status';
+import type { API_MAPS, Exact } from './types';
 
 export class NexAPI<API_INTERFACE extends { [k: string]: any }> {
     #base = 'http://localhost:5000'
-
     #api_maps: API_MAPS<API_INTERFACE>
     #defaults: {
         body?: Record<string, string>
         params?: Record<string, string>
         query?: Record<string, string>
         headers?: Record<string, string>
-    }
+        status: {
+            safe: number,
+            [n: number]: (res: Response) => any
+        }
+    } = {
+            headers: { 'X-Client-Signature': 'restix/0.0.2 (by SignorP)' },
+            status: {
+                safe: Status.OK(undefined).status,
+                201: Status.CREATED,
+                202: Status.ACCEPTED,
+                204: Status.NO_CONTENT,
+                400: () => Status.BAD_REQUEST(
+                    'Invalid request data',
+                    'Check required parameters'
+                ),
+                401: () => Status.UNAUTHORIZED(
+                    'Authentication required'
+                ),
+                403: () => Status.FORBIDDEN(),
+                404: () => Status.NOT_FOUND(),
+                405: () => Status.METHOD_NOT_ALLOWED(),
+                408: () => Status.REQUEST_TIMEOUT(),
+                409: () => Status.CONFLICT(),
+                413: () => Status.PAYLOAD_TOO_LARGE(),
+                415: () => Status.UNSUPPORTED_MEDIA_TYPE(),
+                422: () => Status.UNPROCESSABLE_ENTITY(
+                    'Validation failed'
+                ),
+                429: () => Status.TOO_MANY_REQUESTS(
+                    'Rate limit exceeded',
+                    'Try again later'
+                ),
+                500: () => Status.INTERNAL_ERROR(),
+                501: () => Status.NOT_IMPLEMENTED(),
+                502: () => Status.BAD_GATEWAY(),
+                503: () => Status.SERVICE_UNAVAILABLE(),
+                504: () => Status.GATEWAY_TIMEOUT()
+            }
+        }
 
     constructor(base: string, api_maps: API_MAPS<API_INTERFACE>, defaults?: {
         body?: Record<string, string>
         params?: Record<string, string>
         query?: Record<string, string>
         headers?: Record<string, string>
+        status?: {
+            safe?: number,
+            [n: number]: (res: Response) => any
+        }
     }) {
         this.#base = base
         this.#api_maps = api_maps
-        this.#defaults = defaults ?? {}
+        this.#defaults = { ...defaults, headers: { ...defaults?.headers ?? {}, ...this.#defaults.headers }, status: { ...this.#defaults.status, ...defaults?.status ?? {} } }
     }
 
     async request<URL extends (keyof API_INTERFACE) & string>(prefix: URL, data: Exact<API_INTERFACE[URL], API_INTERFACE[URL]>) {
         const api = this.#api_maps[prefix]
         if (!api) return
+        api.status = { ...this.#defaults.status, ...(api.status ?? {}) }
         data = {
             ...data,
             ...this.#defaults.body ?? {},
@@ -44,12 +87,14 @@ export class NexAPI<API_INTERFACE extends { [k: string]: any }> {
         url = `${this.#base}${url}`
         if (api.map.params.length > 0) url = this.#injectUrlData(url, api.map.params, data)
         if (api.map.query.length > 0) url = this.#injectQuery(url, api.map.query, data)
-        if (api.map.body.length > 0) fetchOptoin.body = JSON.stringify(this.#injectData(api.map.body, data))
-        if (api.map.headers.length > 0) fetchOptoin.headers = this.#injectData(api.map.headers, data)
-        console.log(url, method, { ...fetchOptoin })
+        if (api.map.body.length > 0) {
+            fetchOptoin.body = JSON.stringify(this.#injectData(api.map.body, data))
+            fetchOptoin.headers = { 'Content-type': 'application/json' }
+        }
+        if (api.map.headers.length > 0) fetchOptoin.headers = { ...this.#injectData(api.map.headers, data), ...(fetchOptoin.headers ?? {}) }
         const res = await fetch(url, fetchOptoin)
         if (res.status === api.status.safe) return await res[api.res]()
-        else if (api.status && api.status[res.status]) return api.status[res.status]?.()
+        else if (api.status && api.status[res.status]) return await api.status[res.status]?.(res)
         return undefined
     }
 
@@ -59,11 +104,18 @@ export class NexAPI<API_INTERFACE extends { [k: string]: any }> {
     }
 
     #injectQuery(url: string, queries: string[], data: Record<string, string>) {
-        for (const [i, query] of queries.entries()) {
-            if (i == 0) url = `${url}?${query}=${data[query]}`
-            else url = `${url}&${query}=${data[query]}`
+        for (const query of queries[0] == '*' ? Object.keys(data) : queries) {
+            if (!data[query]) continue
+            const key = `={${query}}`
+            if (url.includes(key)) {
+                url = url.replaceAll(key, `=${data[query]}`)
+                continue
+            }
+            if (!url.includes('?')) url = `${url}?${query}=${data[query]}&`
+            else if (!url.endsWith('&')) url = `${url}&${query}=${data[query]}&`
+            else if (url.endsWith('&')) url = `${url}${query}=${data[query]}&`
         }
-        return url
+        return url.endsWith('&') ? url.slice(0, url.length - 1) : url
     }
 
     #injectData(body: string[], data: Record<string, any>) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restix",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Type-safe HTTP client builder for CLI tools and backend applications",
   "main": "index.js",
   "types": "./index.d.ts",

package/status.d.ts

@@ -0,0 +1,128 @@
+export declare const Status: {
+    readonly OK: <T>(data: T) => {
+        ok: boolean;
+        status: number;
+        data: T;
+    };
+    readonly CREATED: <T>(data: T) => {
+        ok: boolean;
+        status: number;
+        data: T;
+    };
+    readonly ACCEPTED: <T>(data: T) => {
+        ok: boolean;
+        status: number;
+        data: T;
+    };
+    readonly NO_CONTENT: () => {
+        ok: boolean;
+        status: number;
+        data: null;
+    };
+    readonly BAD_REQUEST: (message?: string, hint?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+        hint: string | undefined;
+    };
+    readonly UNAUTHORIZED: (message?: string, hint?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+        hint: string | undefined;
+    };
+    readonly FORBIDDEN: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly NOT_FOUND: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly METHOD_NOT_ALLOWED: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly NOT_ACCEPTABLE: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly REQUEST_TIMEOUT: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly CONFLICT: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly PAYLOAD_TOO_LARGE: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly UNSUPPORTED_MEDIA_TYPE: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly UNPROCESSABLE_ENTITY: (message?: string, hint?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+        hint: string | undefined;
+    };
+    readonly TOO_MANY_REQUESTS: (message?: string, hint?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+        hint: string | undefined;
+    };
+    readonly INTERNAL_ERROR: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly NOT_IMPLEMENTED: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly BAD_GATEWAY: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly SERVICE_UNAVAILABLE: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+    readonly GATEWAY_TIMEOUT: (message?: string) => {
+        ok: boolean;
+        status: number;
+        code: string;
+        message: string;
+    };
+};

package/status.js

@@ -0,0 +1,131 @@
+export const Status = {
+    // ✅ SUCCESS
+    OK: (data) => ({
+        ok: true,
+        status: 200,
+        data
+    }),
+    CREATED: (data) => ({
+        ok: true,
+        status: 201,
+        data
+    }),
+    ACCEPTED: (data) => ({
+        ok: true,
+        status: 202,
+        data
+    }),
+    NO_CONTENT: () => ({
+        ok: true,
+        status: 204,
+        data: null
+    }),
+    // ❌ CLIENT ERRORS
+    BAD_REQUEST: (message = 'Bad request', hint) => ({
+        ok: false,
+        status: 400,
+        code: 'BAD_REQUEST',
+        message,
+        hint
+    }),
+    UNAUTHORIZED: (message = 'Unauthorized', hint) => ({
+        ok: false,
+        status: 401,
+        code: 'UNAUTHORIZED',
+        message,
+        hint
+    }),
+    FORBIDDEN: (message = 'Forbidden') => ({
+        ok: false,
+        status: 403,
+        code: 'FORBIDDEN',
+        message
+    }),
+    NOT_FOUND: (message = 'Not found') => ({
+        ok: false,
+        status: 404,
+        code: 'NOT_FOUND',
+        message
+    }),
+    METHOD_NOT_ALLOWED: (message = 'Method not allowed') => ({
+        ok: false,
+        status: 405,
+        code: 'METHOD_NOT_ALLOWED',
+        message
+    }),
+    NOT_ACCEPTABLE: (message = 'Not acceptable') => ({
+        ok: false,
+        status: 406,
+        code: 'NOT_ACCEPTABLE',
+        message
+    }),
+    REQUEST_TIMEOUT: (message = 'Request timeout') => ({
+        ok: false,
+        status: 408,
+        code: 'REQUEST_TIMEOUT',
+        message
+    }),
+    CONFLICT: (message = 'Conflict') => ({
+        ok: false,
+        status: 409,
+        code: 'CONFLICT',
+        message
+    }),
+    PAYLOAD_TOO_LARGE: (message = 'Payload too large') => ({
+        ok: false,
+        status: 413,
+        code: 'PAYLOAD_TOO_LARGE',
+        message
+    }),
+    UNSUPPORTED_MEDIA_TYPE: (message = 'Unsupported media type') => ({
+        ok: false,
+        status: 415,
+        code: 'UNSUPPORTED_MEDIA_TYPE',
+        message
+    }),
+    UNPROCESSABLE_ENTITY: (message = 'Unprocessable entity', hint) => ({
+        ok: false,
+        status: 422,
+        code: 'UNPROCESSABLE_ENTITY',
+        message,
+        hint
+    }),
+    TOO_MANY_REQUESTS: (message = 'Too many requests', hint) => ({
+        ok: false,
+        status: 429,
+        code: 'TOO_MANY_REQUESTS',
+        message,
+        hint
+    }),
+    // 💥 SERVER ERRORS
+    INTERNAL_ERROR: (message = 'Internal server error') => ({
+        ok: false,
+        status: 500,
+        code: 'INTERNAL_ERROR',
+        message
+    }),
+    NOT_IMPLEMENTED: (message = 'Not implemented') => ({
+        ok: false,
+        status: 501,
+        code: 'NOT_IMPLEMENTED',
+        message
+    }),
+    BAD_GATEWAY: (message = 'Bad gateway') => ({
+        ok: false,
+        status: 502,
+        code: 'BAD_GATEWAY',
+        message
+    }),
+    SERVICE_UNAVAILABLE: (message = 'Service unavailable') => ({
+        ok: false,
+        status: 503,
+        code: 'SERVICE_UNAVAILABLE',
+        message
+    }),
+    GATEWAY_TIMEOUT: (message = 'Gateway timeout') => ({
+        ok: false,
+        status: 504,
+        code: 'GATEWAY_TIMEOUT',
+        message
+    })
+};

package/status.ts

@@ -0,0 +1,151 @@
+export const Status = {
+    // ✅ SUCCESS
+    OK: <T>(data: T) => ({
+        ok: true,
+        status: 200,
+        data
+    }),
+
+    CREATED: <T>(data: T) => ({
+        ok: true,
+        status: 201,
+        data
+    }),
+
+    ACCEPTED: <T>(data: T) => ({
+        ok: true,
+        status: 202,
+        data
+    }),
+
+    NO_CONTENT: () => ({
+        ok: true,
+        status: 204,
+        data: null
+    }),
+
+    // ❌ CLIENT ERRORS
+    BAD_REQUEST: (message = 'Bad request', hint?: string) => ({
+        ok: false,
+        status: 400,
+        code: 'BAD_REQUEST',
+        message,
+        hint
+    }),
+
+    UNAUTHORIZED: (message = 'Unauthorized', hint?: string) => ({
+        ok: false,
+        status: 401,
+        code: 'UNAUTHORIZED',
+        message,
+        hint
+    }),
+
+    FORBIDDEN: (message = 'Forbidden') => ({
+        ok: false,
+        status: 403,
+        code: 'FORBIDDEN',
+        message
+    }),
+
+    NOT_FOUND: (message = 'Not found') => ({
+        ok: false,
+        status: 404,
+        code: 'NOT_FOUND',
+        message
+    }),
+
+    METHOD_NOT_ALLOWED: (message = 'Method not allowed') => ({
+        ok: false,
+        status: 405,
+        code: 'METHOD_NOT_ALLOWED',
+        message
+    }),
+
+    NOT_ACCEPTABLE: (message = 'Not acceptable') => ({
+        ok: false,
+        status: 406,
+        code: 'NOT_ACCEPTABLE',
+        message
+    }),
+
+    REQUEST_TIMEOUT: (message = 'Request timeout') => ({
+        ok: false,
+        status: 408,
+        code: 'REQUEST_TIMEOUT',
+        message
+    }),
+
+    CONFLICT: (message = 'Conflict') => ({
+        ok: false,
+        status: 409,
+        code: 'CONFLICT',
+        message
+    }),
+
+    PAYLOAD_TOO_LARGE: (message = 'Payload too large') => ({
+        ok: false,
+        status: 413,
+        code: 'PAYLOAD_TOO_LARGE',
+        message
+    }),
+
+    UNSUPPORTED_MEDIA_TYPE: (message = 'Unsupported media type') => ({
+        ok: false,
+        status: 415,
+        code: 'UNSUPPORTED_MEDIA_TYPE',
+        message
+    }),
+
+    UNPROCESSABLE_ENTITY: (message = 'Unprocessable entity', hint?: string) => ({
+        ok: false,
+        status: 422,
+        code: 'UNPROCESSABLE_ENTITY',
+        message,
+        hint
+    }),
+
+    TOO_MANY_REQUESTS: (message = 'Too many requests', hint?: string) => ({
+        ok: false,
+        status: 429,
+        code: 'TOO_MANY_REQUESTS',
+        message,
+        hint
+    }),
+
+    // 💥 SERVER ERRORS
+    INTERNAL_ERROR: (message = 'Internal server error') => ({
+        ok: false,
+        status: 500,
+        code: 'INTERNAL_ERROR',
+        message
+    }),
+
+    NOT_IMPLEMENTED: (message = 'Not implemented') => ({
+        ok: false,
+        status: 501,
+        code: 'NOT_IMPLEMENTED',
+        message
+    }),
+
+    BAD_GATEWAY: (message = 'Bad gateway') => ({
+        ok: false,
+        status: 502,
+        code: 'BAD_GATEWAY',
+        message
+    }),
+
+    SERVICE_UNAVAILABLE: (message = 'Service unavailable') => ({
+        ok: false,
+        status: 503,
+        code: 'SERVICE_UNAVAILABLE',
+        message
+    }),
+
+    GATEWAY_TIMEOUT: (message = 'Gateway timeout') => ({
+        ok: false,
+        status: 504,
+        code: 'GATEWAY_TIMEOUT',
+        message
+    })
+} as const

package/test.test.js

@@ -1,13 +1,109 @@
 import { NexAPI } from './api';
 import { apiMap } from './utils';
+/* -------------------------------------------------------
+   API MAPS
+------------------------------------------------------- */
 const api_maps = {
-    'GET /users': {
-        map: apiMap(),
+    // PARAM INJECTION
+    'GET /packages/cli/name/{name}': {
+        map: apiMap({
+            params: ['name']
+        }),
+        res: 'json'
+    },
+    // MULTIPLE PARAMS
+    'GET /packages/cli/name/{name}/{version}': {
+        map: apiMap({
+            params: ['*']
+        }),
         res: 'json',
         status: {
-            safe: 200
+            404: () => 'VERSION NOT FOUND'
         }
+    },
+    // BODY INJECTION
+    'POST /packages/cli/create': {
+        map: apiMap({
+            body: ['*']
+        }),
+        res: 'json',
+        status: {
+            safe: 201,
+            400: () => 'BAD REQUEST'
+        }
+    },
+    // QUERY + HEADER INJECTION
+    'GET /packages/cli/search?selam={v}&VERSION={v}': {
+        map: apiMap({
+            query: ['q', 'v'],
+            headers: ['Authorization']
+        }),
+        res: 'json'
     }
 };
-const api = new NexAPI('http://localhost:5000', api_maps);
-console.log(JSON.stringify(await api.request('GET /users', { selam: 'selam' }), null, 4));
+/* -------------------------------------------------------
+   API INSTANCE
+------------------------------------------------------- */
+const api = new NexAPI('http://localhost:5000', api_maps, {
+    headers: {
+        'User-Agent': 'restix-cli'
+    },
+    status: {
+        404: () => '404 not found for request.'
+    }
+});
+/* -------------------------------------------------------
+   FEATURE SHOWCASE
+------------------------------------------------------- */
+// -----------------------------------------
+// SIMPLE PARAM REQUEST
+// GET /packages/cli/name/xnex
+// -----------------------------------------
+console.log(await api.request('GET /packages/cli/name/{name}', {
+    name: 'xnex'
+}));
+// -----------------------------------------
+// MULTI PARAM REQUEST
+// GET /packages/cli/name/xnex/0.0.1
+// -----------------------------------------
+await api.request('GET /packages/cli/name/{name}/{version}', {
+    name: 'xnex',
+    version: '0.0.1'
+});
+// -----------------------------------------
+// BODY PAYLOAD
+// POST /packages/cli/create
+// -----------------------------------------
+await api.request('POST /packages/cli/create', {
+    name: 'xnex',
+    version: '0.0.1',
+    developer: 'Signor P'
+});
+// -----------------------------------------
+// QUERY + HEADER
+// GET /packages/cli/search?query=nex
+// Header: token
+// -----------------------------------------
+await api.request('GET /packages/cli/search?selam={v}&VERSION={v}', {
+    q: 'nex',
+    v: 'sa',
+    Authorization: 'Bearer AUTH_TOKEN'
+});
+// -----------------------------------------
+// TYPE SAFETY DEMO (INTENTIONAL ERRORS)
+// -----------------------------------------
+// ❌ extra field not allowed
+// await api.request(
+//     'GET /packages/cli/name/{name}',
+//     {
+//         name: 'xnex',
+//         extra: 'nope'
+//     }
+// )
+// ❌ missing field
+// await api.request(
+//     'POST /packages/cli/create',
+//     {
+//         name: 'xnex'
+//     }
+// )

package/test.test.ts

@@ -1,19 +1,174 @@
 import { NexAPI } from './api'
-import type { API_MAPS } from './types'
+import type { API_MAPS, GET_API } from './types'
 import { apiMap } from './utils'
 
+/* -------------------------------------------------------
+   API CONTRACT
+------------------------------------------------------- */
+
 interface API_INTERFACE {
-    'GET /users': {}
+    'GET /packages/cli/name/{name}': {
+        name: string
+    }
+
+    'GET /packages/cli/name/{name}/{version}': {
+        name: string
+        version: string
+    }
+
+    'POST /packages/cli/create': {
+        name: string
+        version: string
+        developer: string
+    }
+
+    'GET /packages/cli/search?selam={v}&VERSION={v}': {
+        q: string
+        v?: string,
+        Authorization: string
+    }
 }
+
+/* -------------------------------------------------------
+   API MAPS
+------------------------------------------------------- */
+
 const api_maps: API_MAPS<API_INTERFACE> = {
-    'GET /users': {
-        map: apiMap(),
+
+    // PARAM INJECTION
+    'GET /packages/cli/name/{name}': {
+        map: apiMap<GET_API<API_INTERFACE, 'GET /packages/cli/name/{name}'>>({
+            params: ['name']
+        }),
+        res: 'json'
+    },
+
+    // MULTIPLE PARAMS
+    'GET /packages/cli/name/{name}/{version}': {
+        map: apiMap<GET_API<API_INTERFACE, 'GET /packages/cli/name/{name}/{version}'>>({
+            params: ['*']
+        }),
         res: 'json',
         status: {
-            safe: 200
+            404: () => 'VERSION NOT FOUND'
         }
+    },
+
+    // BODY INJECTION
+    'POST /packages/cli/create': {
+        map: apiMap<GET_API<API_INTERFACE, 'POST /packages/cli/create'>>({
+            body: ['*']
+        }),
+        res: 'json',
+        status: {
+            safe: 201,
+            400: () => 'BAD REQUEST'
+        }
+    },
+
+    // QUERY + HEADER INJECTION
+    'GET /packages/cli/search?selam={v}&VERSION={v}': {
+        map: apiMap<GET_API<API_INTERFACE, 'GET /packages/cli/search?selam={v}&VERSION={v}'>>({
+            query: ['q', 'v'],
+            headers: ['Authorization']
+        }),
+        res: 'json'
     }
 }
 
-const api = new NexAPI<API_INTERFACE>('http://localhost:5000', api_maps)
-console.log(JSON.stringify(await api.request('GET /users', { selam: 'selam' }), null, 4))
+/* -------------------------------------------------------
+   API INSTANCE
+------------------------------------------------------- */
+
+const api = new NexAPI<API_INTERFACE>(
+    'http://localhost:5000',
+    api_maps,
+    {
+        headers: {
+            'User-Agent': 'restix-cli'
+        },
+        status: {
+            404: () => '404 not found for request.'
+        }
+    }
+)
+
+/* -------------------------------------------------------
+   FEATURE SHOWCASE
+------------------------------------------------------- */
+
+
+// -----------------------------------------
+// SIMPLE PARAM REQUEST
+// GET /packages/cli/name/xnex
+// -----------------------------------------
+console.log(await api.request(
+    'GET /packages/cli/name/{name}',
+    {
+        name: 'xnex'
+    }
+))
+
+
+// -----------------------------------------
+// MULTI PARAM REQUEST
+// GET /packages/cli/name/xnex/0.0.1
+// -----------------------------------------
+await api.request(
+    'GET /packages/cli/name/{name}/{version}',
+    {
+        name: 'xnex',
+        version: '0.0.1'
+    }
+)
+
+
+// -----------------------------------------
+// BODY PAYLOAD
+// POST /packages/cli/create
+// -----------------------------------------
+await api.request(
+    'POST /packages/cli/create',
+    {
+        name: 'xnex',
+        version: '0.0.1',
+        developer: 'Signor P'
+    }
+)
+
+
+// -----------------------------------------
+// QUERY + HEADER
+// GET /packages/cli/search?query=nex
+// Header: token
+// -----------------------------------------
+await api.request(
+    'GET /packages/cli/search?selam={v}&VERSION={v}',
+    {
+        q: 'nex',
+        v: 'sa',
+        Authorization: 'Bearer AUTH_TOKEN'
+    }
+)
+
+
+// -----------------------------------------
+// TYPE SAFETY DEMO (INTENTIONAL ERRORS)
+// -----------------------------------------
+
+// ❌ extra field not allowed
+// await api.request(
+//     'GET /packages/cli/name/{name}',
+//     {
+//         name: 'xnex',
+//         extra: 'nope'
+//     }
+// )
+
+// ❌ missing field
+// await api.request(
+//     'POST /packages/cli/create',
+//     {
+//         name: 'xnex'
+//     }
+// )

package/types.d.ts

@@ -8,9 +8,9 @@ export type Exact<T, Shape extends T> = T & Record<Exclude<keyof Shape, keyof T>
 export interface API_MAP_TYPE<K extends string> {
     map: ApiMapShape<K>;
     res: keyof Pick<Response, 'json' | 'text' | 'blob'>;
-    status: {
-        safe: number;
-        [k: number]: () => any;
+    status?: {
+        safe?: number;
+        [n: number]: (res: Response) => any;
     };
 }
 export type API_MAPS<T extends Record<string, any>> = {

package/types.ts

@@ -11,9 +11,9 @@ export type Exact<T, Shape extends T> =
 export interface API_MAP_TYPE<K extends string> {
     map: ApiMapShape<K>
     res: keyof Pick<Response, 'json' | 'text' | 'blob'>
-    status: {
-        safe: number
-        [k: number]: () => any
+    status?: {
+        safe?: number,
+        [n: number]: (res: Response) => any
     }
 }