lambder 1.0.129 → 1.0.131

package/examples/msw-correct-usage.ts

@@ -0,0 +1,136 @@
+/**
+ * CORRECT USAGE: Lambder MSW Integration Example
+ * 
+ * This demonstrates the proper way to use MSW with Lambder.
+ * Each mockLambderApi call returns an MSW RequestHandler that can be used directly.
+ */
+
+// Step 1: Define your API contract
+import type { ApiContractShape } from '../src/index.js';
+
+const ApiContract = {
+  'public.getInitialPageData': {
+    input: null,
+    output: {
+      userLocationData: {
+        country: '' as string,
+        region: '' as string,
+        regionCode: '' as string,
+        city: '' as string,
+        zipCode: '' as string,
+        lat: 0 as number,
+        lng: 0 as number,
+      },
+      sessionUser: null as null | {
+        id: string;
+        username: string;
+        email: string;
+        name: string;
+        bio: string;
+      }
+    }
+  },
+  'user.updateProfile': {
+    input: {
+      name: '' as string,
+      bio: '' as string
+    },
+    output: {
+      success: true as boolean
+    }
+  }
+} satisfies ApiContractShape;
+
+type MyApiContract = typeof ApiContract;
+
+// Step 2: Create mock handlers using Lambder's utility functions
+import { mockLambderApi } from '../src/index.js';
+
+export const handlers = [
+  // Each mockLambderApi call returns a proper MSW RequestHandler
+  // You can use them directly in setupWorker/setupServer
+  mockLambderApi<MyApiContract, 'public.getInitialPageData'>(
+    'public.getInitialPageData',
+    () => ({
+      userLocationData: {
+        country: 'United States',
+        region: 'California',
+        regionCode: 'CA',
+        city: 'San Francisco',
+        zipCode: '94102',
+        lat: 37.7749,
+        lng: -122.4194,
+      },
+      sessionUser: {
+        id: 'mock-user-123',
+        username: 'mockuser',
+        email: 'mock@example.com',
+        name: 'Mock User',
+        bio: 'This is a mock user for development',
+      },
+    })
+  ),
+
+  mockLambderApi<MyApiContract, 'user.updateProfile'>(
+    'user.updateProfile',
+    (input) => {
+      console.log('Updating profile:', input);
+      return {
+        success: true
+      };
+    },
+    {
+      delay: 500 // Optional: simulate network delay
+    }
+  ),
+];
+
+// Step 3: Set up MSW
+// For Browser (development):
+/**
+ * ```typescript
+ * // src/mocks/browser.ts
+ * import { setupWorker } from 'msw/browser';
+ * import { handlers } from './handlers';
+ * 
+ * export const worker = setupWorker(...handlers);
+ * 
+ * // src/main.tsx
+ * if (import.meta.env.DEV) {
+ *   const { worker } = await import('./mocks/browser');
+ *   worker.start();
+ * }
+ * ```
+ */
+
+// For Node.js (testing):
+/**
+ * ```typescript
+ * // src/mocks/server.ts
+ * import { setupServer } from 'msw/node';
+ * import { handlers } from './handlers';
+ * 
+ * export const server = setupServer(...handlers);
+ * 
+ * // vitest.setup.ts
+ * import { server } from './mocks/server';
+ * 
+ * beforeAll(() => server.listen());
+ * afterEach(() => server.resetHandlers());
+ * afterAll(() => server.close());
+ * ```
+ */
+
+// Type verification: handlers is an array of MSW RequestHandler
+// TypeScript should infer this correctly without needing explicit types
+export type HandlersType = typeof handlers; // RequestHandler[]
+
+/**
+ * KEY POINTS:
+ * 
+ * 1. mockLambderApi returns a proper MSW RequestHandler (from http.post)
+ * 2. You can spread handlers directly into setupWorker/setupServer
+ * 3. Each handler checks body.apiName and only responds to its specific API
+ * 4. Full type safety with your API contract
+ * 5. No need to import HttpHandler type - MSW provides RequestHandler
+ */

package/examples/msw-mocking-example.ts

@@ -0,0 +1,241 @@
+/**
+ * Example: Using MSW to mock Lambder API endpoints
+ * 
+ * This example demonstrates how to use Mock Service Worker (MSW) with Lambder
+ * to create type-safe mocks for your API endpoints.
+ * 
+ * Prerequisites:
+ * - Install MSW: npm install --save-dev msw
+ * - Define your API contract
+ */
+
+import { 
+  mockLambderApi, 
+  mockLambderApiError,
+  mockLambderSessionExpired,
+  mockLambderNotAuthorized,
+  mockLambderVersionExpired,
+  type ApiContractShape 
+} from '../src/index.js';
+
+// 1. Define your API contract
+const myApiContract = {
+  'user.getProfile': {
+    input: { userId: '' as string },
+    output: { name: '' as string, email: '' as string, role: '' as string }
+  },
+  'user.updateProfile': {
+    input: { userId: '' as string, name: '' as string, email: '' as string },
+    output: { success: true as boolean, message: '' as string }
+  },
+  'user.deleteAccount': {
+    input: { userId: '' as string },
+    output: { success: true as boolean }
+  },
+  'admin.listUsers': {
+    input: { page: 0 as number, limit: 0 as number },
+    output: { users: [] as Array<{ id: string; name: string }>, total: 0 as number }
+  }
+} satisfies ApiContractShape;
+
+type MyApiContract = typeof myApiContract;
+
+// 2. Create mock handlers
+
+// Basic success mock
+export const getUserProfileHandler = mockLambderApi<MyApiContract, 'user.getProfile'>(
+  'user.getProfile',
+  (input) => {
+    console.log('Mocking user.getProfile for userId:', input.userId);
+    
+    // Return mock data with full type safety
+    return {
+      name: 'John Doe',
+      email: 'john@example.com',
+      role: 'user'
+    };
+  }
+);
+
+// Mock with dynamic response based on input
+export const updateProfileHandler = mockLambderApi<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  (input) => {
+    console.log('Mocking user.updateProfile:', input);
+    
+    // Validate input
+    if (!input.name || input.name.length < 2) {
+      throw new Error('Name must be at least 2 characters');
+    }
+    
+    return {
+      success: true,
+      message: `Profile updated for ${input.name}`
+    };
+  },
+  {
+    delay: 500 // Simulate network delay
+  }
+);
+
+// Mock with error response
+export const updateProfileErrorHandler = mockLambderApiError<MyApiContract, 'user.updateProfile'>(
+  'user.updateProfile',
+  'Failed to update profile due to server error',
+  {
+    delay: 300
+  }
+);
+
+// Mock session expired
+export const deleteAccountSessionExpiredHandler = mockLambderSessionExpired<MyApiContract, 'user.deleteAccount'>(
+  'user.deleteAccount'
+);
+
+// Mock not authorized
+export const listUsersNotAuthorizedHandler = mockLambderNotAuthorized<MyApiContract, 'admin.listUsers'>(
+  'admin.listUsers'
+);
+
+// Mock version expired
+export const getProfileVersionExpiredHandler = mockLambderVersionExpired<MyApiContract, 'user.getProfile'>(
+  'user.getProfile'
+);
+
+// Mock with pagination
+export const listUsersHandler = mockLambderApi<MyApiContract, 'admin.listUsers'>(
+  'admin.listUsers',
+  (input) => {
+    // Generate mock paginated data
+    const allUsers = Array.from({ length: 50 }, (_, i) => ({
+      id: `user-${i + 1}`,
+      name: `User ${i + 1}`
+    }));
+    
+    const start = input.page * input.limit;
+    const end = start + input.limit;
+    const users = allUsers.slice(start, end);
+    
+    return {
+      users,
+      total: allUsers.length
+    };
+  }
+);
+
+// 3. Set up MSW handlers
+
+// For Node.js testing (Vitest, Jest, etc.)
+/**
+ * Setup example for Node.js tests:
+ * 
+ * ```typescript
+ * // test-setup.ts
+ * import { setupServer } from 'msw/node';
+ * import { getUserProfileHandler, updateProfileHandler } from './msw-example';
+ * 
+ * export const server = setupServer(
+ *   getUserProfileHandler,
+ *   updateProfileHandler,
+ *   listUsersHandler
+ * );
+ * 
+ * // vitest.setup.ts
+ * beforeAll(() => server.listen());
+ * afterEach(() => server.resetHandlers());
+ * afterAll(() => server.close());
+ * ```
+ */
+
+// For browser development/Storybook
+/**
+ * Setup example for browser:
+ * 
+ * ```typescript
+ * // mocks/browser.ts
+ * import { setupWorker } from 'msw/browser';
+ * import { getUserProfileHandler, updateProfileHandler } from './msw-example';
+ * 
+ * export const worker = setupWorker(
+ *   getUserProfileHandler,
+ *   updateProfileHandler,
+ *   listUsersHandler
+ * );
+ * 
+ * // main.tsx
+ * if (import.meta.env.DEV) {
+ *   const { worker } = await import('./mocks/browser');
+ *   worker.start();
+ * }
+ * ```
+ */
+
+// 4. Using in tests
+
+/**
+ * Test example:
+ * 
+ * ```typescript
+ * import { describe, it, expect } from 'vitest';
+ * import { server } from './test-setup';
+ * import { caller } from './api-client';
+ * 
+ * describe('User Profile', () => {
+ *   it('should get user profile', async () => {
+ *     const profile = await caller.api('user.getProfile', { userId: '123' });
+ *     
+ *     expect(profile).toEqual({
+ *       name: 'John Doe',
+ *       email: 'john@example.com',
+ *       role: 'user'
+ *     });
+ *   });
+ * 
+ *   it('should handle update errors', async () => {
+ *     // Override handler for this test
+ *     server.use(updateProfileErrorHandler);
+ *     
+ *     const result = await caller.api('user.updateProfile', {
+ *       userId: '123',
+ *       name: 'New Name',
+ *       email: 'new@example.com'
+ *     });
+ *     
+ *     expect(result).toBeNull(); // Error handler returns null
+ *   });
+ * 
+ *   it('should handle session expiry', async () => {
+ *     server.use(deleteAccountSessionExpiredHandler);
+ *     
+ *     const result = await caller.api('user.deleteAccount', { userId: '123' });
+ *     
+ *     expect(result).toBeNull();
+ *     // Verify sessionExpiredHandler was called if configured
+ *   });
+ * 
+ *   it('should handle not authorized', async () => {
+ *     server.use(listUsersNotAuthorizedHandler);
+ *     
+ *     const result = await caller.api('admin.listUsers', { page: 0, limit: 10 });
+ *     
+ *     expect(result).toBeNull();
+ *     // Verify notAuthorizedHandler was called if configured
+ *   });
+ * });
+ * ```
+ */
+
+// Export all handlers for easy setup
+export const handlers = [
+  getUserProfileHandler,
+  updateProfileHandler,
+  listUsersHandler,
+];
+
+// Export error handlers separately
+export const errorHandlers = [
+  updateProfileErrorHandler,
+  deleteAccountSessionExpiredHandler,
+  listUsersNotAuthorizedHandler,
+  getProfileVersionExpiredHandler,
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "1.0.129",
+  "version": "1.0.131",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,14 @@
     "path-to-regexp": "^6.2.1",
     "querystring": "^0.2.1"
   },
+  "peerDependencies": {
+    "msw": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "msw": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.136",
     "@types/cookie": "^0.6.0",

package/src/LambderMSW.ts

@@ -0,0 +1,295 @@
+import type { ApiContractShape } from './LambderApiContract.js';
+
+/**
+ * Creates a mock handler for a Lambder API endpoint
+ * 
+ * @example
+ * ```typescript
+ * mockLambderApi('public.getInitialPageData', () => ({
+ *   userLocationData: { ... },
+ *   sessionUser: null
+ * }))
+ * ```
+ * 
+ * @example with dynamic response based on input
+ * ```typescript
+ * mockLambderApi('user.updateProfile', (input) => ({
+ *   success: true,
+ *   userId: input.userId
+ * }))
+ * ```
+ */
+export function mockLambderApi<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    responseFactory: (
+        input: TContract[TApiName]['input']
+    ) => TContract[TApiName]['output'] | Promise<TContract[TApiName]['output']>,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string
+        /** Delay in ms before responding (for testing loading states) */
+        delay?: number
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null
+    }
+) {
+    const apiPath = options?.apiPath ?? '/api';
+    const delay = options?.delay ?? 0;
+    const apiVersion = options?.apiVersion ?? null;
+
+    // @ts-ignore - MSW is an optional peer dependency
+    const { http, HttpResponse } = require('msw');
+
+    return http.post(apiPath, async ({ request }: any) => {
+        const body = (await request.json()) as {
+            apiName: string;
+            payload?: TContract[TApiName]['input'];
+            version?: string;
+            token?: string;
+            siteHost?: string;
+        };
+
+        // Only handle this specific API
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking ${apiName}`, body.payload);
+
+        // Apply delay if specified
+        if (delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+
+        // Generate the response
+        const payload = await responseFactory(body.payload as TContract[TApiName]['input']);
+
+        // Return in Lambder API response format
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload,
+        });
+    });
+}
+
+/**
+ * Creates a mock handler that returns an error for a Lambder API endpoint
+ * 
+ * @example
+ * ```typescript
+ * mockLambderApiError('user.deleteAccount', 'Account deletion failed')
+ * ```
+ */
+export function mockLambderApiError<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    errorMessage: string,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Delay in ms before responding */
+        delay?: number;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+) {
+    const apiPath = options?.apiPath ?? '/api';
+    const delay = options?.delay ?? 0;
+    const apiVersion = options?.apiVersion ?? null;
+
+    // @ts-ignore - MSW is an optional peer dependency
+    const { http, HttpResponse } = require('msw');
+
+    return http.post(apiPath, async ({ request }: any) => {
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking error for ${apiName}:`, errorMessage);
+
+        if (delay > 0) {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            errorMessage,
+        });
+    });
+}
+
+/**
+ * Creates a mock handler that simulates a session expired error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderSessionExpired('user.updateProfile')
+ * ```
+ */
+export function mockLambderSessionExpired<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    // @ts-ignore - MSW is an optional peer dependency
+    const { http, HttpResponse } = require('msw');
+
+    return http.post(apiPath, async ({ request }: any) => {
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking session expired for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            sessionExpired: true,
+            errorMessage: 'Session expired',
+        });
+    });
+}
+
+/**
+ * Creates a mock handler that simulates a "not authorized" error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderNotAuthorized('admin.deleteUser')
+ * ```
+ */
+export function mockLambderNotAuthorized<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    // @ts-ignore - MSW is an optional peer dependency
+    const { http, HttpResponse } = require('msw');
+
+    return http.post(apiPath, async ({ request }: any) => {
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking not authorized for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            notAuthorized: true,
+            errorMessage: 'Not authorized',
+        });
+    });
+}
+
+/**
+ * Creates a mock handler that simulates a version expired error
+ * 
+ * @example
+ * ```typescript
+ * mockLambderVersionExpired('user.updateProfile')
+ * ```
+ */
+export function mockLambderVersionExpired<
+    TContract extends ApiContractShape,
+    TApiName extends keyof TContract & string
+>(
+    apiName: TApiName,
+    options?: {
+        /** Custom API path, defaults to '/api' */
+        apiPath?: string;
+        /** Custom apiVersion to include in response */
+        apiVersion?: string | null;
+    }
+) {
+    const apiPath = options?.apiPath ?? '/api';
+    const apiVersion = options?.apiVersion ?? null;
+
+    // @ts-ignore - MSW is an optional peer dependency
+    const { http, HttpResponse } = require('msw');
+
+    return http.post(apiPath, async ({ request }: any) => {
+        const body = (await request.json()) as { 
+            apiName: string; 
+            payload?: any;
+        };
+
+        if (body.apiName !== apiName) {
+            return;
+        }
+
+        console.log(`[MSW Lambder] Mocking version expired for ${apiName}`);
+
+        return HttpResponse.json({
+            ...(apiVersion !== null ? { apiVersion } : {}),
+            payload: null,
+            versionExpired: true,
+            errorMessage: 'Version expired',
+        });
+    });
+}
+
+/**
+ * Helper to combine multiple Lambder mock handlers
+ * Since each handler checks for its specific apiName, you can just spread them into setupWorker/setupServer
+ * 
+ * @deprecated This helper is not needed - just spread handlers directly into setupWorker/setupServer
+ * @example
+ * ```typescript
+ * import { setupServer } from 'msw/node';
+ * 
+ * const server = setupServer(
+ *   mockLambderApi('user.getProfile', () => ({ name: 'Test User' })),
+ *   mockLambderApi('user.updateProfile', (input) => ({ success: true }))
+ * );
+ * ```
+ */
+export function createLambderApiHandler(
+    apiPath: string,
+    handlers: any[]
+) {
+    // This is deprecated - users should just spread handlers directly
+    // Kept for backward compatibility
+    return handlers;
+}

package/src/index.ts

@@ -13,3 +13,13 @@ export {
     type ApiInput,
     type ApiOutput,
 } from "./LambderApiContract.js";
+
+// MSW mocking utilities (optional - requires msw to be installed)
+export {
+    mockLambderApi,
+    mockLambderApiError,
+    mockLambderSessionExpired,
+    mockLambderNotAuthorized,
+    mockLambderVersionExpired,
+    createLambderApiHandler,
+} from "./LambderMSW.js";