lambder 1.0.125 → 1.0.126

package/Readme.md

@@ -485,6 +485,65 @@ const loadPageData = async () => {
 };
 ```
 
+## Type-Safe APIs (Optional)
+
+Want compile-time type checking for your APIs? It's incredibly simple!
+
+### 1. Define Your API Contract
+
+```typescript
+// shared/apiContract.ts
+import type { ApiContract } from 'lambder';
+
+export type MyApiContract = {
+    getUserById: { input: { userId: string }, output: User },
+    createUser: { input: CreateUserInput, output: User },
+    listUsers: { input: void, output: User[] }
+} satisfies ApiContract;
+```
+
+### 2. Backend - Pass Type to Constructor
+
+```typescript
+import Lambder from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const lambder = new Lambder<MyApiContract>({ publicPath: './public', apiPath: '/api' });
+
+// Now addApi is type-safe!
+lambder.addApi('getUserById', async (ctx, resolver) => {
+    // ctx.apiPayload is automatically typed as { userId: string } ✨
+    const user = await db.getUser(ctx.apiPayload.userId);
+    return resolver.api(user);
+});
+```
+
+### 3. Frontend - Pass Type to Constructor
+
+```typescript
+import { LambderCaller } from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const caller = new LambderCaller<MyApiContract>({ apiPath: '/api', isCorsEnabled: false });
+
+// Now api() is type-safe with full autocomplete! ✨
+const user = await caller.api('getUserById', { userId: '123' });
+//                             ↑ IDE shows all available APIs
+//                                            ↑ Type-checked input
+// user is typed as User | null | undefined
+```
+
+### Benefits
+
+✅ **Simple** - Just pass type to constructor, that's it!  
+✅ **Autocomplete** - IDE suggests available APIs as you type  
+✅ **Type Safety** - Inputs and outputs are fully typed  
+✅ **No Wrappers** - Use existing `api()` and `addApi()` methods  
+✅ **Opt-In** - Add when you want, skip when you don't  
+✅ **Zero Overhead** - Pure TypeScript types, no runtime code  
+
+📖 **[Read the Quick Start Guide](docs/TYPE_SAFE_QUICK_START.md)** for more details and examples!
+
 ## Contributing
 
 Contributions are welcome! Especially for documentation. If you have an idea for an improvement or have found a bug, please open an issue or submit a pull request.

package/dist/Lambder.d.ts

@@ -4,6 +4,7 @@ import LambderResponseBuilder, { LambderResolverResponse } from "./LambderRespon
 import LambderUtils from "./LambderUtils.js";
 import { type LambderSessionContext } from "./LambderSessionManager.js";
 import LambderSessionController from "./LambderSessionController.js";
+import type { ApiContract } from "./LambderApiContract.js";
 type Path = `/${string}`;
 export type LambderRenderContext = {
     host: string;
@@ -43,7 +44,7 @@ type GlobalErrorHandlerFunction = (err: Error, ctx: LambderRenderContext | null,
 type RouteFallbackHandlerFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
 type ApiFallbackHandlerFunction = (ctx: LambderRenderContext, resolver: LambderResolver) => LambderResolverResponse;
 export declare const createContext: (event: APIGatewayProxyEvent, lambdaContext: Context, apiPath: string) => LambderRenderContext;
-export default class Lambder {
+export default class Lambder<TContract extends ApiContract = any> {
     apiPath: string;
     apiVersion: null | string;
     isCorsEnabled: boolean;
@@ -86,8 +87,16 @@ export default class Lambder {
     }>): Promise<void>;
     addRoute(condition: Path | ConditionFunction | RegExp, actionFn: ActionFunction): void;
     addSessionRoute(condition: Path | ConditionFunction | RegExp, actionFn: ActionFunction): void;
-    addApi(apiName: string | ConditionFunction | RegExp, actionFn: ActionFunction): void;
-    addSessionApi(apiName: string | ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addApi(apiName: ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addApi<TApiName extends keyof TContract & string>(apiName: TApiName, actionFn: (ctx: LambderRenderContext & {
+        apiPayload: TContract[TApiName]['input'];
+    }, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>): void;
+    addApi(apiName: string, actionFn: ActionFunction): void;
+    addSessionApi(apiName: ConditionFunction | RegExp, actionFn: ActionFunction): void;
+    addSessionApi<TApiName extends keyof TContract & string>(apiName: TApiName, actionFn: (ctx: LambderRenderContext & {
+        apiPayload: TContract[TApiName]['input'];
+    }, resolver: LambderResolver) => LambderResolverResponse | Promise<LambderResolverResponse>): void;
+    addSessionApi(apiName: string, actionFn: ActionFunction): void;
     addHook(hookEvent: 'created', hookFn: HookCreatedFunction, priority?: number): Promise<void>;
     addHook(hookEvent: 'beforeRender', hookFn: HookBeforeRenderFunction, priority?: number): Promise<void>;
     addHook(hookEvent: 'afterRender', hookFn: HookAfterRenderFunction, priority?: number): Promise<void>;

package/dist/Lambder.js

@@ -163,6 +163,7 @@ export default class Lambder {
         });
     }
     ;
+    // Implementation
     addApi(apiName, actionFn) {
         this.actionList.push({
             conditionFn: (ctx) => (!!ctx.apiName && ((typeof apiName === "string" && ctx.apiName === apiName) ||
@@ -172,6 +173,7 @@ export default class Lambder {
         });
     }
     ;
+    // Implementation
     addSessionApi(apiName, actionFn) {
         this.actionList.push({
             conditionFn: (ctx) => (!!ctx.apiName && ((typeof apiName === "string" && ctx.apiName === apiName) ||

package/dist/LambderApiContract.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Type-safe API Contract System
+ *
+ * Define your API contract as a TypeScript type to get full type safety
+ * across frontend and backend with no runtime overhead.
+ *
+ * Example:
+ *
+ * export type MyApiContract = {
+ *     getUserById: { input: { userId: string }, output: User },
+ *     createUser: { input: CreateUserInput, output: User },
+ *     listUsers: { input: void, output: User[] }
+ * }
+ *
+ * Frontend:
+ * const caller = new LambderCaller<MyApiContract>({ ... });
+ * const user = await caller.api('getUserById', { userId: '123' }); // typed!
+ *
+ * Backend:
+ * const lambder = new Lambder<MyApiContract>({ ... });
+ * lambder.addApi('getUserById', async (ctx, resolver) => {
+ *     // ctx.apiPayload is typed as { userId: string }
+ *     return resolver.api(user); // user is typed as User
+ * });
+ */
+/**
+ * Base type for API contracts
+ */
+export type ApiContract = {
+    [apiName: string]: {
+        input: any;
+        output: any;
+    };
+};
+/**
+ * Extract input type from contract for a specific API
+ */
+export type ApiInput<TContract extends ApiContract, TApiName extends keyof TContract> = TContract[TApiName]['input'];
+/**
+ * Extract output type from contract for a specific API
+ */
+export type ApiOutput<TContract extends ApiContract, TApiName extends keyof TContract> = TContract[TApiName]['output'];

package/dist/LambderApiContract.js

@@ -0,0 +1,26 @@
+/**
+ * Type-safe API Contract System
+ *
+ * Define your API contract as a TypeScript type to get full type safety
+ * across frontend and backend with no runtime overhead.
+ *
+ * Example:
+ *
+ * export type MyApiContract = {
+ *     getUserById: { input: { userId: string }, output: User },
+ *     createUser: { input: CreateUserInput, output: User },
+ *     listUsers: { input: void, output: User[] }
+ * }
+ *
+ * Frontend:
+ * const caller = new LambderCaller<MyApiContract>({ ... });
+ * const user = await caller.api('getUserById', { userId: '123' }); // typed!
+ *
+ * Backend:
+ * const lambder = new Lambder<MyApiContract>({ ... });
+ * lambder.addApi('getUserById', async (ctx, resolver) => {
+ *     // ctx.apiPayload is typed as { userId: string }
+ *     return resolver.api(user); // user is typed as User
+ * });
+ */
+export {};

package/dist/LambderCaller.d.ts

@@ -1,4 +1,5 @@
 import { LambderApiResponse } from './LambderResponseBuilder';
+import type { ApiContract } from './LambderApiContract';
 type VoidFunction = () => void | Promise<void>;
 type FetchTracker = {
     apiName: string;
@@ -21,7 +22,7 @@ type FetchEndEventHandler = (params: {
 }) => void | Promise<void>;
 type ErrorHandler = (err: Error) => void | Promise<void>;
 type MessageHandler = (message: any) => void | Promise<void>;
-export default class LambderCaller {
+export default class LambderCaller<TContract extends ApiContract = any> {
     private isCorsEnabled;
     private apiPath;
     private apiVersion?;
@@ -51,7 +52,7 @@ export default class LambderCaller {
         fetchEndedHandler?: FetchEndEventHandler;
     });
     setSessionCookieKey(sessionTokenCookieKey: string, sessionCsrfCookieKey: string): void;
-    apiRaw<T = any>(apiName: string, payload?: any, options?: {
+    apiRaw<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: {
         headers?: Record<string, any>;
         versionExpiredHandler?: VoidFunction;
         sessionExpiredHandler?: VoidFunction;
@@ -61,7 +62,17 @@ export default class LambderCaller {
         errorHandler?: ErrorHandler;
         fetchStartedHandler?: FetchStartEventHandler;
         fetchEndedHandler?: FetchEndEventHandler;
-    }): Promise<LambderApiResponse<T> | null | undefined>;
-    api<T = any>(...params: Parameters<typeof LambderCaller.prototype.apiRaw>): Promise<T | null | undefined>;
+    }): Promise<LambderApiResponse<TOutput> | null | undefined>;
+    api<TApiName extends keyof TContract & string = string, TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any>(apiName: TApiName, payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any, options?: {
+        headers?: Record<string, any>;
+        versionExpiredHandler?: VoidFunction;
+        sessionExpiredHandler?: VoidFunction;
+        messageHandler?: MessageHandler;
+        errorMessageHandler?: MessageHandler;
+        notAuthorizedHandler?: VoidFunction;
+        errorHandler?: ErrorHandler;
+        fetchStartedHandler?: FetchStartEventHandler;
+        fetchEndedHandler?: FetchEndEventHandler;
+    }): Promise<TOutput | null | undefined>;
 }
 export {};

package/dist/LambderCaller.js

@@ -131,8 +131,8 @@ export default class LambderCaller {
     }
     ;
     // Use the same type for api but adjust the return type
-    async api(...params) {
-        const result = await this.apiRaw(...params);
+    async api(apiName, payload, options) {
+        const result = await this.apiRaw(apiName, payload, options);
         return result?.payload;
     }
 }

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export { default as LambderCaller } from "./LambderCaller.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
+export { type ApiContract, type ApiInput, type ApiOutput, } from "./LambderApiContract.js";

package/docs/TYPE_SAFE_QUICK_START.md

@@ -0,0 +1,123 @@
+# Type-Safe API Quick Start
+
+## In 3 Simple Steps
+
+### 1. Define Your Contract Type
+
+```typescript
+// shared/apiContract.ts
+import type { ApiContract } from 'lambder';
+
+export type MyApiContract = {
+    getUserById: { input: { userId: string }, output: User },
+    createUser: { input: CreateUserInput, output: User },
+    listUsers: { input: void, output: User[] }
+} satisfies ApiContract;
+```
+
+### 2. Backend - Pass Type to Lambder
+
+```typescript
+import Lambder from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const lambder = new Lambder<MyApiContract>({
+    publicPath: './public',
+    apiPath: '/api'
+});
+
+// Now addApi is type-safe!
+lambder.addApi('getUserById', async (ctx, resolver) => {
+    // ctx.apiPayload is automatically typed as { userId: string }
+    const user = await db.getUser(ctx.apiPayload.userId);
+    return resolver.api(user);
+});
+```
+
+### 3. Frontend - Pass Type to LambderCaller
+
+```typescript
+import { LambderCaller } from 'lambder';
+import type { MyApiContract } from './shared/apiContract';
+
+const caller = new LambderCaller<MyApiContract>({
+    apiPath: '/api',
+    isCorsEnabled: false
+});
+
+// Now api() is type-safe!
+const user = await caller.api('getUserById', { userId: '123' });
+// user is typed as User | null | undefined
+```
+
+## That's It!
+
+- ✅ **No wrapper functions needed**
+- ✅ **Use existing `api()` and `addApi()` methods**
+- ✅ **Full autocomplete in IDE**
+- ✅ **Type-safe inputs and outputs**
+- ✅ **Backward compatible**
+
+## Contract Type Format
+
+```typescript
+type MyApiContract = {
+    apiName: { input: InputType, output: OutputType }
+}
+```
+
+## Examples
+
+### API with parameters
+```typescript
+getUserById: { input: { userId: string }, output: User }
+```
+
+### API with no input
+```typescript
+listAll: { input: void, output: Item[] }
+```
+
+### API with complex types
+```typescript
+updateUser: { 
+    input: { id: string } & Partial<User>, 
+    output: User 
+}
+```
+
+### API with conditional output
+```typescript
+login: { 
+    input: { email: string, password: string },
+    output: { success: boolean, user?: User, error?: string }
+}
+```
+
+## Without Type Safety (Still Works!)
+
+Don't want type safety? Just don't pass the generic type:
+
+```typescript
+// Frontend
+const caller = new LambderCaller({ ... }); // No generic
+await caller.api('anyApi', { anything: true }); // Works, but untyped
+
+// Backend
+const lambder = new Lambder({ ... }); // No generic
+lambder.addApi('anyApi', async (ctx, resolver) => {
+    // ctx.apiPayload is any
+});
+```
+
+## Full Example
+
+See [simplified-typed-api-example.ts](../examples/simplified-typed-api-example.ts) for a complete working example.
+
+## Key Points
+
+- **Contract is just a TypeScript type** - No runtime code!
+- **Zero overhead** - All type checking happens at compile time
+- **Opt-in** - Use types when you want them
+- **Simple** - Just pass type to constructor
+- **Autocomplete** - IDE shows available APIs as you type

package/examples/simplified-typed-api-example.ts

@@ -0,0 +1,365 @@
+/**
+ * Simplified Type-Safe API Example
+ * 
+ * This example shows how to use Lambder's opt-in type-safe API system.
+ * Simply pass your API contract type to LambderCaller and Lambder constructors,
+ * and get full type safety with no extra wrapper functions needed!
+ */
+
+import Lambder from '../src/Lambder.js';
+import LambderCaller from '../src/LambderCaller.js';
+import type { ApiContract } from '../src/index.js';
+
+// ============================================================================
+// Step 1: Define your data types
+// ============================================================================
+
+type User = {
+    id: string;
+    name: string;
+    email: string;
+    role: 'admin' | 'user';
+    createdAt: string;
+};
+
+type CreateUserInput = {
+    name: string;
+    email: string;
+    password: string;
+};
+
+type UpdateUserInput = {
+    userId: string;
+    name?: string;
+    email?: string;
+};
+
+type LoginInput = {
+    email: string;
+    password: string;
+};
+
+type LoginOutput = {
+    success: boolean;
+    user?: User;
+    token?: string;
+    error?: string;
+};
+
+// ============================================================================
+// Step 2: Define your API contract (shared between frontend and backend)
+// ============================================================================
+
+export type MyApiContract = {
+    // API with input and output
+    getUserById: { input: { userId: string }, output: User },
+    
+    // API with complex input/output
+    createUser: { input: CreateUserInput, output: User },
+    updateUser: { input: UpdateUserInput, output: User },
+    
+    // API with void input (no parameters needed)
+    listUsers: { input: void, output: User[] },
+    getCurrentUser: { input: void, output: User },
+    
+    // API with conditional output
+    login: { input: LoginInput, output: LoginOutput },
+    
+    // API with primitive output
+    getUserCount: { input: void, output: number },
+    deleteUser: { input: { userId: string }, output: boolean },
+}
+
+// ============================================================================
+// Step 3: Backend - Pass contract type to Lambder
+// ============================================================================
+
+export function setupBackend() {
+    // Pass the contract type as a generic parameter
+    const lambder = new Lambder<MyApiContract>({
+        publicPath: './public',
+        apiPath: '/api',
+        apiVersion: '1.0.0',
+    });
+
+    // Now addApi is type-safe! ctx.apiPayload is automatically typed!
+    lambder.addApi('getUserById', async (ctx, resolver) => {
+        // ctx.apiPayload is typed as { userId: string }
+        const userId = ctx.apiPayload.userId; // ✅ TypeScript knows this!
+        
+        // Mock database call
+        const user: User = {
+            id: userId,
+            name: 'John Doe',
+            email: 'john@example.com',
+            role: 'user',
+            createdAt: new Date().toISOString(),
+        };
+        
+        return resolver.api(user);
+    });
+
+    // Session API with typed payload
+    lambder.addSessionApi('createUser', async (ctx, resolver) => {
+        // ctx.apiPayload is typed as CreateUserInput
+        const { name, email, password } = ctx.apiPayload;
+        
+        // Validation with type safety
+        if (!name || !email || !password) {
+            return resolver.api(null, {
+                errorMessage: 'Missing required fields'
+            });
+        }
+        
+        // Create user
+        const newUser: User = {
+            id: Math.random().toString(36).substr(2, 9),
+            name,
+            email,
+            role: 'user',
+            createdAt: new Date().toISOString(),
+        };
+        
+        return resolver.api(newUser);
+    });
+
+    // API with void input
+    lambder.addApi('listUsers', async (ctx, resolver) => {
+        // ctx.apiPayload is void/undefined
+        const users: User[] = [
+            { id: '1', name: 'John', email: 'john@example.com', role: 'user', createdAt: new Date().toISOString() },
+            { id: '2', name: 'Jane', email: 'jane@example.com', role: 'admin', createdAt: new Date().toISOString() },
+        ];
+        
+        return resolver.api(users);
+    });
+
+    // Complex API with conditional response
+    lambder.addApi('login', async (ctx, resolver) => {
+        // ctx.apiPayload is typed as LoginInput
+        const { email, password } = ctx.apiPayload;
+        
+        // Mock authentication
+        if (email === 'test@example.com' && password === 'password123') {
+            const result: LoginOutput = {
+                success: true,
+                user: {
+                    id: '1',
+                    name: 'Test User',
+                    email: email,
+                    role: 'user',
+                    createdAt: new Date().toISOString(),
+                },
+                token: 'mock-jwt-token',
+            };
+            return resolver.api(result);
+        } else {
+            const result: LoginOutput = {
+                success: false,
+                error: 'Invalid credentials',
+            };
+            return resolver.api(result);
+        }
+    });
+
+    // You can still use RegExp or functions for dynamic patterns (untyped)
+    lambder.addApi(/^admin\./, async (ctx, resolver) => {
+        // ctx.apiPayload is any (untyped)
+        return resolver.api({ message: 'Admin API' });
+    });
+
+    return lambder;
+}
+
+// ============================================================================
+// Step 4: Frontend - Pass contract type to LambderCaller
+// ============================================================================
+
+export function setupFrontend() {
+    // Pass the contract type as a generic parameter
+    const caller = new LambderCaller<MyApiContract>({
+        apiPath: '/api',
+        apiVersion: '1.0.0',
+        isCorsEnabled: false,
+        errorHandler: (err) => {
+            console.error('API Error:', err);
+        },
+    });
+
+    // Now all API calls are type-safe!
+    
+    // Example 1: Get user by ID
+    async function example1() {
+        // TypeScript knows:
+        // - First parameter is 'getUserById' (autocomplete shows all API names!)
+        // - Second parameter must be { userId: string }
+        // - Return type is User | null | undefined
+        const user = await caller.api('getUserById', { userId: '123' });
+        
+        if (user) {
+            console.log(user.name); // ✅ TypeScript knows 'name' exists
+            console.log(user.email); // ✅ TypeScript knows 'email' exists
+            console.log(user.role); // ✅ TypeScript knows 'role' is 'admin' | 'user'
+            // console.log(user.age); // ✗ Error: Property 'age' does not exist
+        }
+    }
+
+    // Example 2: Create user
+    async function example2() {
+        // TypeScript enforces the CreateUserInput type
+        const newUser = await caller.api('createUser', {
+            name: 'Alice',
+            email: 'alice@example.com',
+            password: 'secret123',
+        });
+        
+        if (newUser) {
+            console.log('Created user:', newUser.id);
+        }
+        
+        // This would be a TypeScript error:
+        // await caller.api('createUser', { name: 'Bob' }); // ✗ Missing email and password
+    }
+
+    // Example 3: Login
+    async function example3() {
+        const result = await caller.api('login', {
+            email: 'test@example.com',
+            password: 'password123',
+        });
+        
+        if (result?.success && result.user) {
+            console.log('Logged in as:', result.user.name);
+            console.log('Token:', result.token);
+        } else {
+            console.error('Login failed:', result?.error);
+        }
+    }
+
+    // Example 4: List users (void input)
+    async function example4() {
+        // For void input, pass undefined
+        const users = await caller.api('listUsers', undefined);
+        
+        if (users) {
+            users.forEach(user => {
+                console.log(user.name); // ✅ TypeScript knows the array type
+            });
+        }
+    }
+
+    // Example 5: Get user count (primitive output)
+    async function example5() {
+        const count = await caller.api('getUserCount', undefined);
+        if (count !== null && count !== undefined) {
+            console.log(`Total users: ${count}`); // count is number
+        }
+    }
+
+    // Example 6: With custom headers
+    async function example6() {
+        const user = await caller.api(
+            'getUserById',
+            { userId: '456' },
+            { headers: { 'X-Custom-Header': 'value' } }
+        );
+    }
+
+    // Example 7: Using apiRaw for full response
+    async function example7() {
+        const response = await caller.apiRaw('getUserById', { userId: '123' });
+        
+        if (response) {
+            console.log('Payload:', response.payload); // User | null
+            if (response.logList) {
+                console.log('Logs:', response.logList);
+            }
+            if (response.errorMessage) {
+                console.error('Error:', response.errorMessage);
+            }
+        }
+    }
+
+    return caller;
+}
+
+// ============================================================================
+// Without Contract (Backward Compatibility)
+// ============================================================================
+
+export function setupWithoutContract() {
+    // If you don't pass a contract type, it works like before (untyped)
+    const caller = new LambderCaller({
+        apiPath: '/api',
+        isCorsEnabled: false,
+    });
+
+    // Still works, but no type safety
+    async function untypedExample() {
+        const user = await caller.api('getUserById', { userId: '123' });
+        // user is any
+    }
+
+    const lambder = new Lambder({
+        publicPath: './public',
+        apiPath: '/api',
+    });
+
+    // Still works, but no type safety
+    lambder.addApi('getUserById', async (ctx, resolver) => {
+        // ctx.apiPayload is any
+        const user = { id: ctx.apiPayload.userId, name: 'User' };
+        return resolver.api(user);
+    });
+}
+
+// ============================================================================
+// Type Safety Examples
+// ============================================================================
+
+export function typeSafetyExamples() {
+    const caller = new LambderCaller<MyApiContract>({ apiPath: '/api', isCorsEnabled: false });
+
+    async function examples() {
+        // ✓ VALID:
+        await caller.api('getUserById', { userId: '123' });
+        await caller.api('createUser', { name: 'Alice', email: 'alice@example.com', password: 'pass' });
+        await caller.api('listUsers', undefined);
+
+        // ✗ ERRORS (TypeScript prevents):
+        // await caller.api('getUserById'); // Missing required payload
+        // await caller.api('getUserById', { id: '123' }); // Wrong property name (should be userId)
+        // await caller.api('createUser', { name: 'Bob' }); // Missing email and password
+        // await caller.api('nonExistentApi', {}); // API doesn't exist in contract
+        
+        // Type inference works:
+        const user = await caller.api('getUserById', { userId: '123' });
+        if (user) {
+            console.log(user.name); // ✓ TypeScript knows user has name
+            // console.log(user.age); // ✗ Error: Property 'age' does not exist
+        }
+
+        const users = await caller.api('listUsers', undefined);
+        if (users) {
+            users.forEach(u => {
+                console.log(u.email); // ✓ TypeScript knows array item structure
+            });
+        }
+    }
+}
+
+// ============================================================================
+// Key Benefits
+// ============================================================================
+// 
+// 1. ✅ Type Safety - Frontend and backend share the same types
+// 2. ✅ Autocomplete - IDE suggests available APIs as you type
+// 3. ✅ No Wrappers - Use existing api() and addApi() methods
+// 4. ✅ Opt-In - Add types when you want, or don't use them at all
+// 5. ✅ Backward Compatible - Existing code works without changes
+// 6. ✅ Simple - Just pass type to constructor, that's it!
+// 7. ✅ Zero Runtime Overhead - Pure TypeScript types
+//
+// ============================================================================
+
+export { Lambder, LambderCaller, type ApiContract };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.125",
+  "version": "1.0.126",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/Lambder.ts

@@ -8,6 +8,7 @@ import LambderResponseBuilder, { LambderResolverResponse } from "./LambderRespon
 import LambderUtils from "./LambderUtils.js";
 import LambderSessionManager, { type LambderSessionContext } from "./LambderSessionManager.js";
 import LambderSessionController from "./LambderSessionController.js";
+import type { ApiContract } from "./LambderApiContract.js";
 
 type Path = `/${string}`;
 
@@ -92,7 +93,7 @@ export const createContext = (
 }
 
 
-export default class Lambder {
+export default class Lambder<TContract extends ApiContract = any> {
     public apiPath: string;
     public apiVersion: null|string;
     public isCorsEnabled: boolean = false;
@@ -238,6 +239,25 @@ export default class Lambder {
         });
     };
     
+    // Overload for untyped API with RegExp or function
+    addApi(
+        apiName: ConditionFunction|RegExp,
+        actionFn: ActionFunction
+    ):void;
+    // Overload for typed API with string name (must come before untyped string overload)
+    addApi<TApiName extends keyof TContract & string>(
+        apiName: TApiName,
+        actionFn: (
+            ctx: LambderRenderContext & { apiPayload: TContract[TApiName]['input'] },
+            resolver: LambderResolver
+        ) => LambderResolverResponse|Promise<LambderResolverResponse>
+    ):void;
+    // Overload for untyped API with string (backward compatibility, must be last)
+    addApi(
+        apiName: string,
+        actionFn: ActionFunction
+    ):void;
+    // Implementation
     addApi(apiName: string|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
             conditionFn: (ctx:LambderRenderContext) =>  (
@@ -251,6 +271,25 @@ export default class Lambder {
         });
     };
 
+    // Overload for untyped session API with RegExp or function
+    addSessionApi(
+        apiName: ConditionFunction|RegExp,
+        actionFn: ActionFunction
+    ):void;
+    // Overload for typed session API with string name (must come before untyped string overload)
+    addSessionApi<TApiName extends keyof TContract & string>(
+        apiName: TApiName,
+        actionFn: (
+            ctx: LambderRenderContext & { apiPayload: TContract[TApiName]['input'] },
+            resolver: LambderResolver
+        ) => LambderResolverResponse|Promise<LambderResolverResponse>
+    ):void;
+    // Overload for untyped session API with string (backward compatibility, must be last)
+    addSessionApi(
+        apiName: string,
+        actionFn: ActionFunction
+    ):void;
+    // Implementation
     addSessionApi(apiName: string|ConditionFunction|RegExp, actionFn: ActionFunction):void{
         this.actionList.push({ 
             conditionFn: (ctx:LambderRenderContext) =>  (

package/src/LambderApiContract.ts

@@ -0,0 +1,51 @@
+/**
+ * Type-safe API Contract System
+ * 
+ * Define your API contract as a TypeScript type to get full type safety
+ * across frontend and backend with no runtime overhead.
+ * 
+ * Example:
+ * 
+ * export type MyApiContract = {
+ *     getUserById: { input: { userId: string }, output: User },
+ *     createUser: { input: CreateUserInput, output: User },
+ *     listUsers: { input: void, output: User[] }
+ * }
+ * 
+ * Frontend:
+ * const caller = new LambderCaller<MyApiContract>({ ... });
+ * const user = await caller.api('getUserById', { userId: '123' }); // typed!
+ * 
+ * Backend:
+ * const lambder = new Lambder<MyApiContract>({ ... });
+ * lambder.addApi('getUserById', async (ctx, resolver) => {
+ *     // ctx.apiPayload is typed as { userId: string }
+ *     return resolver.api(user); // user is typed as User
+ * });
+ */
+
+/**
+ * Base type for API contracts
+ */
+export type ApiContract = {
+    [apiName: string]: {
+        input: any;
+        output: any;
+    }
+}
+
+/**
+ * Extract input type from contract for a specific API
+ */
+export type ApiInput<
+    TContract extends ApiContract,
+    TApiName extends keyof TContract
+> = TContract[TApiName]['input'];
+
+/**
+ * Extract output type from contract for a specific API
+ */
+export type ApiOutput<
+    TContract extends ApiContract,
+    TApiName extends keyof TContract
+> = TContract[TApiName]['output'];

package/src/LambderCaller.ts

@@ -1,5 +1,6 @@
 import Cookies from 'js-cookie';
 import { LambderApiResponse } from './LambderResponseBuilder';
+import type { ApiContract } from './LambderApiContract';
 
 type VoidFunction = ()=>void|Promise<void>;
 type FetchTracker = { apiName: string, done: boolean, fetchEndCalled: boolean };
@@ -23,7 +24,7 @@ type FetchEndEventHandler = (params: {
 type ErrorHandler = (err: Error) => void|Promise<void>;
 type MessageHandler = (message:any) => void|Promise<void>;
 
-export default class LambderCaller {
+export default class LambderCaller<TContract extends ApiContract = any> {
     private isCorsEnabled: boolean;
     private apiPath: string;
     private apiVersion?: string; 
@@ -90,17 +91,24 @@ export default class LambderCaller {
         this.sessionCsrfCookieKey = sessionCsrfCookieKey;
     }
     
-    async apiRaw<T=any>(apiName: string, payload?: any, options?: {
-        headers?: Record<string, any>
-        versionExpiredHandler?: VoidFunction, 
-        sessionExpiredHandler?: VoidFunction, 
-        messageHandler?: MessageHandler,
-        errorMessageHandler?: MessageHandler,
-        notAuthorizedHandler?: VoidFunction, 
-        errorHandler?: ErrorHandler, 
-        fetchStartedHandler?: FetchStartEventHandler, 
-        fetchEndedHandler?: FetchEndEventHandler,
-    }): Promise<LambderApiResponse<T>|null|undefined>{
+    async apiRaw<
+        TApiName extends keyof TContract & string = string,
+        TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any
+    >(
+        apiName: TApiName,
+        payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any,
+        options?: {
+            headers?: Record<string, any>
+            versionExpiredHandler?: VoidFunction, 
+            sessionExpiredHandler?: VoidFunction, 
+            messageHandler?: MessageHandler,
+            errorMessageHandler?: MessageHandler,
+            notAuthorizedHandler?: VoidFunction, 
+            errorHandler?: ErrorHandler, 
+            fetchStartedHandler?: FetchStartEventHandler, 
+            fetchEndedHandler?: FetchEndEventHandler,
+        }
+    ): Promise<LambderApiResponse<TOutput>|null|undefined>{
         const headers = options?.headers;
         const fetchTracker: FetchTracker = { apiName, done: false, fetchEndCalled: false };
         try {
@@ -125,7 +133,7 @@ export default class LambderCaller {
                 }else{
                     return res.json();
                 }
-            }) as LambderApiResponse<T>;
+            }) as LambderApiResponse<TOutput>;
             fetchTracker.done = true;
             if(this.fetchEndedHandler){
                 fetchTracker.fetchEndCalled = true;
@@ -189,8 +197,25 @@ export default class LambderCaller {
     };
     
     // Use the same type for api but adjust the return type
-    async api<T=any>(...params: Parameters<typeof LambderCaller.prototype.apiRaw>): Promise<T|null|undefined> {
-        const result = await this.apiRaw<T>(...params);
+    async api<
+        TApiName extends keyof TContract & string = string,
+        TOutput = TApiName extends keyof TContract ? TContract[TApiName]['output'] : any
+    >(
+        apiName: TApiName,
+        payload?: TApiName extends keyof TContract ? TContract[TApiName]['input'] : any,
+        options?: {
+            headers?: Record<string, any>
+            versionExpiredHandler?: VoidFunction, 
+            sessionExpiredHandler?: VoidFunction, 
+            messageHandler?: MessageHandler,
+            errorMessageHandler?: MessageHandler,
+            notAuthorizedHandler?: VoidFunction, 
+            errorHandler?: ErrorHandler, 
+            fetchStartedHandler?: FetchStartEventHandler, 
+            fetchEndedHandler?: FetchEndEventHandler,
+        }
+    ): Promise<TOutput|null|undefined> {
+        const result = await this.apiRaw<TApiName, TOutput>(apiName, payload, options);
         return result?.payload;
     }
 

package/src/index.ts

@@ -5,3 +5,10 @@ export { default as LambderCaller } from "./LambderCaller.js";
 export { default as LambderResponseBuilder } from "./LambderResponseBuilder.js";
 export { default as LambderResolver } from "./LambderResolver.js";
 export { default as LambderSessionManager } from "./LambderSessionManager.js";
+
+// Type-safe API contract utilities
+export { 
+    type ApiContract,
+    type ApiInput,
+    type ApiOutput,
+} from "./LambderApiContract.js";

package/tests/type-safety.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Type Safety Tests
+ * 
+ * This file tests that the type system works correctly.
+ * If this file compiles without errors, the types are working!
+ */
+
+import Lambder from '../src/Lambder.js';
+import LambderCaller from '../src/LambderCaller.js';
+import type { ApiContract } from '../src/index.js';
+
+// Test contract
+type TestApiContract = {
+    getUser: { input: { userId: string }, output: { id: string, name: string } },
+    createUser: { input: { name: string, email: string }, output: { id: string, name: string, email: string } },
+    listUsers: { input: void, output: Array<{ id: string, name: string }> },
+    deleteUser: { input: { userId: string }, output: boolean }
+}
+
+// ============================================================================
+// Test 1: LambderCaller Type Safety
+// ============================================================================
+
+function testCallerTypes() {
+    const caller = new LambderCaller<TestApiContract>({
+        apiPath: '/api',
+        isCorsEnabled: false
+    });
+
+    async function test() {
+        // ✅ Should work: Correct types
+        const user1 = await caller.api('getUser', { userId: '123' });
+        const user2 = await caller.api('createUser', { name: 'Alice', email: 'alice@example.com' });
+        const users = await caller.api('listUsers', undefined);
+        const deleted = await caller.api('deleteUser', { userId: '123' });
+
+        // Type assertions to verify return types
+        if (user1) {
+            const name: string = user1.name; // Should work
+            const id: string = user1.id; // Should work
+        }
+
+        if (user2) {
+            const email: string = user2.email; // Should work
+        }
+
+        if (users) {
+            const firstUser = users[0];
+            if (firstUser) {
+                const name: string = firstUser.name; // Should work
+            }
+        }
+
+        if (deleted !== null && deleted !== undefined) {
+            const result: boolean = deleted; // Should work
+        }
+
+        // ❌ These should cause TypeScript errors (commented out to allow compilation):
+        
+        // Wrong property name
+        // await caller.api('getUser', { id: '123' }); // Error: should be userId
+        
+        // Missing required property
+        // await caller.api('createUser', { name: 'Bob' }); // Error: missing email
+        
+        // Wrong type
+        // await caller.api('getUser', { userId: 123 }); // Error: userId should be string
+        
+        // Non-existent API
+        // await caller.api('nonExistent', {}); // Error: API doesn't exist
+        
+        // Wrong payload for void input
+        // await caller.api('listUsers', { something: true }); // Error: should be undefined
+    }
+}
+
+// ============================================================================
+// Test 2: Lambder Type Safety
+// ============================================================================
+
+function testLambderTypes() {
+    const lambder = new Lambder<TestApiContract>({
+        publicPath: './public',
+        apiPath: '/api'
+    });
+
+    // ✅ Should work: Typed API
+    lambder.addApi('getUser', async (ctx, resolver) => {
+        // ctx.apiPayload should be typed as { userId: string }
+        const userId: string = ctx.apiPayload.userId; // Should work
+        
+        // Return correct type
+        return resolver.api({ id: userId, name: 'Test' });
+    });
+
+    // ✅ Should work: Typed session API
+    lambder.addSessionApi('createUser', async (ctx, resolver) => {
+        // ctx.apiPayload should be typed as { name: string, email: string }
+        const name: string = ctx.apiPayload.name;
+        const email: string = ctx.apiPayload.email;
+        
+        return resolver.api({ id: '1', name, email });
+    });
+
+    // ✅ Should work: Void input API
+    lambder.addApi('listUsers', async (ctx, resolver) => {
+        // ctx.apiPayload should be void/undefined
+        return resolver.api([
+            { id: '1', name: 'User 1' },
+            { id: '2', name: 'User 2' }
+        ]);
+    });
+
+    // ✅ Should work: RegExp (untyped)
+    lambder.addApi(/^admin\./, async (ctx, resolver) => {
+        // ctx.apiPayload is any (untyped)
+        return resolver.api({});
+    });
+
+    // ❌ These should cause TypeScript errors (commented out):
+    
+    // Accessing wrong property
+    // lambder.addApi('getUser', async (ctx, resolver) => {
+    //     const id = ctx.apiPayload.id; // Error: should be userId
+    //     return resolver.api({ id, name: 'Test' });
+    // });
+    
+    // Returning wrong type
+    // lambder.addApi('getUser', async (ctx, resolver) => {
+    //     return resolver.api({ id: '1' }); // Error: missing name property
+    // });
+}
+
+// ============================================================================
+// Test 3: Backward Compatibility (No Contract)
+// ============================================================================
+
+function testBackwardCompatibility() {
+    // Without contract type - should work as before (untyped)
+    const caller = new LambderCaller({
+        apiPath: '/api',
+        isCorsEnabled: false
+    });
+
+    const lambder = new Lambder({
+        publicPath: './public',
+        apiPath: '/api'
+    });
+
+    async function test() {
+        // Should work - untyped
+        const result = await caller.api('anyApi', { anything: true });
+        
+        lambder.addApi('anyApi', async (ctx, resolver) => {
+            // ctx.apiPayload is any
+            return resolver.api({ anything: ctx.apiPayload });
+        });
+    }
+}
+
+// ============================================================================
+// Test 4: apiRaw Method
+// ============================================================================
+
+function testApiRaw() {
+    const caller = new LambderCaller<TestApiContract>({
+        apiPath: '/api',
+        isCorsEnabled: false
+    });
+
+    async function test() {
+        // apiRaw should also be typed
+        const response = await caller.apiRaw('getUser', { userId: '123' });
+        
+        if (response) {
+            // response.payload should be typed
+            const user = response.payload;
+            if (user) {
+                const name: string = user.name; // Should work
+                const id: string = user.id; // Should work
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Test 5: Complex Types
+// ============================================================================
+
+type ComplexApiContract = {
+    update: { 
+        input: { id: string } & Partial<{ name: string, email: string }>, 
+        output: { id: string, name: string, email: string } 
+    },
+    search: { 
+        input: { query: string, filters?: { role?: string, active?: boolean } }, 
+        output: Array<{ id: string, name: string }> 
+    }
+}
+
+function testComplexTypes() {
+    const caller = new LambderCaller<ComplexApiContract>({
+        apiPath: '/api',
+        isCorsEnabled: false
+    });
+
+    async function test() {
+        // Should work with partial update
+        await caller.api('update', { id: '1', name: 'New Name' });
+        await caller.api('update', { id: '1', email: 'new@email.com' });
+        await caller.api('update', { id: '1' }); // Only id
+
+        // Should work with optional nested object
+        await caller.api('search', { query: 'test' });
+        await caller.api('search', { query: 'test', filters: { role: 'admin' } });
+        await caller.api('search', { query: 'test', filters: { role: 'admin', active: true } });
+    }
+}
+
+// ============================================================================
+// If this file compiles without errors, the type system is working! ✅
+// ============================================================================
+
+export { };