lambder 1.0.124 → 1.0.126

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.124",
+  "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}`;
 
@@ -23,6 +24,7 @@ export type LambderRenderContext = {
     apiPayload: any;
     headers: APIGatewayProxyEventHeaders;
     session: LambderSessionContext|null;
+    event: APIGatewayProxyEvent;
     lambdaContext: Context;
     _otherInternal: { 
         isApiCall: boolean,
@@ -78,7 +80,7 @@ export const createContext = (
 
     return { 
         host, path, pathParams, method, 
-        get, post, cookie, 
+        get, post, cookie, event,
         apiName, apiPayload, 
         headers, session, lambdaContext, 
         _otherInternal: { 
@@ -91,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;
@@ -133,7 +135,7 @@ export default class Lambder {
         this.utils = new LambderUtils({ ejsPath });
     }
 
-    setIsCorsEnabled(isCorsEnabled: boolean){
+    enableCors(isCorsEnabled: boolean){
         this.isCorsEnabled = isCorsEnabled;
     }
 
@@ -237,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) =>  (
@@ -250,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 {
@@ -117,10 +125,15 @@ export default class LambderCaller {
                 credentials: 'same-origin', redirect: 'follow', referrerPolicy: 'origin',
                 headers: { 'Content-Type': 'application/json', ...(headers || {}) },
                 body: JSON.stringify({ apiName, version, token, siteHost, payload, }),
-            }).then(res=>{
+            }).then(async (res)=>{
                 if(res.status >= 500) throw new Error("Request failed: " + res.status + " - " + res.statusText);
-                return res.json();
-            }) as LambderApiResponse<T>;
+                if(res.headers.get("Content-Type")?.includes("application/lambder-json-stream")){ 
+                    const decompressed = res.json();
+                    return decompressed;
+                }else{
+                    return res.json();
+                }
+            }) as LambderApiResponse<TOutput>;
             fetchTracker.done = true;
             if(this.fetchEndedHandler){
                 fetchTracker.fetchEndCalled = true;
@@ -157,7 +170,7 @@ export default class LambderCaller {
                 if(this.notAuthorizedHandler){
                     await this.notAuthorizedHandler();
                 }else if(this.errorHandler){
-                    await this.errorHandler(new Error("Version Expired; Please refresh;"));
+                    await this.errorHandler(new Error("Not Authorized;"));
                 }
                 return null;
             }
@@ -184,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/LambderResponseBuilder.ts

@@ -199,7 +199,11 @@ export default class LambderResponseBuilder {
         }
         const mimeType = mimeTypeResolver.lookup(filePath);
         const body = this.readPublicFileSync(filePath);
-        const bodyBase64 = Buffer.from(body).toString("base64");
+        if (body === "forbidden-public-path") {
+            throw { error: "Forbidden public path: " + filePath };
+        }
+        const bodyBuffer: Buffer =  Buffer.isBuffer(body) ? body : Buffer.from(body);
+        const bodyBase64 = bodyBuffer.toString("base64");
         console.log("bodyBase64.length",bodyBase64.length);
         return this.fileBase64(bodyBase64, mimeType || "", headers);
     };
@@ -258,4 +262,39 @@ export default class LambderResponseBuilder {
         }, headers);
     };
 
+    private apiBinary<T=any>(
+        payload: T | null, 
+        {
+            versionExpired, sessionExpired, notAuthorized, 
+            message, errorMessage, logList,
+        }: LambderApiResponseConfig = {
+            versionExpired: undefined, sessionExpired: undefined, notAuthorized: undefined, 
+            message: null, errorMessage: null, logList: undefined
+        }, 
+        headers?: Record<string, string|string[]>,
+    ): LambderResolverResponse {
+        const finalLogList = logList || this.ctx?._otherInternal?.logToApiResponseAccumulator;
+        const result = { 
+            apiVersion: this.apiVersion,
+            payload,
+            ...(versionExpired ? {versionExpired} : {}),
+            ...(sessionExpired ? {sessionExpired} : {}),
+            ...(notAuthorized ? {notAuthorized} : {}),
+            ...(message ? {message} : {}),
+            ...(errorMessage ? {errorMessage} : {}),
+            ...(finalLogList?.length ? {logList: finalLogList} : {}),
+        };
+
+        return this.raw({ 
+            statusCode: 200, 
+            isBase64Encoded: true, 
+            multiValueHeaders: { 
+                "Content-Type": ["application/lambder-json-stream"],
+                "Content-Encoding": ["gzip"],
+                ...convertToMultiHeader(headers) 
+            }, 
+            body: Buffer.from(JSON.stringify(result)).toString("base64"), 
+        });
+    };
+
 };

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";