@nlabs/metropolisjs 1.0.8 → 1.1.0

package/README.md

@@ -1,7 +1,7 @@
 # MetropolisJS: Seamless Frontend-Backend Integration Framework
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/nitrogenlabs/metropolisjs/main/docs/assets/metropolisjs-logo.png" alt="MetropolisJS logo" width="432">
+  <img src="https://raw.githubusercontent.com/nitrogenlabs/metropolisjs/main/docs/assets/metropolisjs-mark.svg" alt="MetropolisJS winged V logo" width="432">
 </p>
 
 > **The Ultimate Frontend Integration Library for Modern Web Applications**
@@ -183,7 +183,7 @@ Configure the public analytics identifier returned by Reaktor under `app.rum.ana
 </Metropolis>
 ```
 
-The endpoint is resolved from `app.api.endpoints.rum`, falling back to `app.api.rum`. RUM delivery is unauthenticated and each batch contains `analyticsId` and up to 50 sanitized events.
+Configure the endpoint at `app.api.endpoints.rum`. RUM delivery is unauthenticated and each batch contains `analyticsId` and up to 50 sanitized events.
 
 #### Beacon delivery
 
@@ -450,7 +450,7 @@ const LoginForm = () => {
 
   const handleLogin = async () => {
     try {
-      const session = await userActions.signIn(username, password);
+      const session = await userActions.signIn({password, username});
       console.log('User logged in successfully!', session);
     } catch (error) {
       console.error('Login failed:', error);
@@ -476,6 +476,41 @@ const LoginForm = () => {
 };
 ```
 
+### Billing Setup Sessions
+
+Billing cards are collected through a hosted setup session, so raw card details never pass through application code. Start the flow with an authenticated user action and redirect the browser to the returned checkout URL:
+
+```tsx
+import {useUserActions} from '@nlabs/metropolisjs';
+
+const AddBillingCardButton = () => {
+  const userActions = useUserActions();
+
+  const addBillingCard = async () => {
+    const returnUrl = `${window.location.origin}/settings/billing/complete`;
+    const checkoutUrl = await userActions.createBillingSetupSession(returnUrl);
+    window.location.assign(checkoutUrl);
+  };
+
+  return <button onClick={addBillingCard}>Add billing card</button>;
+};
+```
+
+On the return page, read the provider's setup-session identifier and complete the flow. The action returns the updated user, refreshes the matching session data, dispatches the standard user update event, and clears related user request caches:
+
+```tsx
+const sessionId = new URLSearchParams(window.location.search).get('session_id');
+
+if(sessionId) {
+  const user = await userActions.completeBillingSetupSession(sessionId, [
+    'stripeCardBrand',
+    'stripeCardLast4'
+  ]);
+}
+```
+
+Use `deleteBillingCard()` to remove the saved billing method. Both completion and deletion return sanitized billing metadata; MetropolisJS does not accept raw card numbers or tokens.
+
 ### Real-Time Messaging
 
 ```tsx
@@ -597,21 +632,34 @@ MetropolisJS uses a **factory function pattern** for actions. This provides func
 ### Basic Usage
 
 ```typescript
-import {createUserActions} from '../actions/userActions';
+import {createAction, createActions, createUserActions} from '@nlabs/metropolisjs';
 
 const userActions = createUserActions(flux);
-const user = await userActions.add(userData);
+const user = await userActions.addUser(userData);
+
+const postActions = createAction('post', flux);
+const post = await postActions.add({content: 'Hello!'});
+
+const actions = createActions(['user', 'post', 'message'], flux);
+await actions.message.sendMessage({
+  content: 'Welcome!',
+  recipientId: user.userId
+});
 ```
 
+Factory results preserve their selected types. `createAction('post', flux)` returns `PostActions`, while `createActions(['user', 'post'], flux)` returns only typed `user` and `post` keys. `createAllActions(flux)` returns the complete `ActionMap`.
+
 ### Advanced Usage with Custom Adapters
 
 #### Custom Validation Adapter
 
 ```typescript
+import type {User} from '@nlabs/metropolisjs';
+
 // Custom adapter that extends default behavior
-const customUserAdapter = (input: unknown, options?: UserAdapterOptions) => {
+const customUserAdapter = (input: unknown): User => {
   // input is already validated by default adapter
-  const user = input as any;
+  const user = input as User;
 
   // Add business-specific validation
   if (user.email && !user.email.includes('@company.com')) {
@@ -622,7 +670,7 @@ const customUserAdapter = (input: unknown, options?: UserAdapterOptions) => {
   return {
     ...user,
     fullName: `${user.firstName || ''} ${user.lastName || ''}`.trim(),
-    isAdmin: user.userAccess >= 3
+    isAdmin: (user.userAccess || 0) >= 3
   };
 };
 
@@ -688,31 +736,7 @@ interface AdapterOptions {
 }
 ```
 
-### Migration Guide
-
-#### Step 1: Update Imports
-
-```typescript
-// Old
-import {userActions} from '../actions/userActions';
-
-// New
-import {createUserActions} from '../actions/userActions';
-```
-
-#### Step 2: Update Instantiation
-
-```typescript
-// Old
-const userActions = new userActions(flux, customAdapter);
-
-// New
-const userActions = createUserActions(flux, {
-  userAdapter: customAdapter
-});
-```
-
-#### Step 3: Using Actions in Components
+### Using Actions in Components
 
 The recommended approach is to use specialized hooks:
 
@@ -765,11 +789,11 @@ const apiUrl = config.app?.api?.url || '';
 #### Unit Testing Actions
 
 ```typescript
-import {createUserActions} from '@nlabs/metropolisjs';
+import {createUserActions, type UserActions} from '@nlabs/metropolisjs';
 
 describe('userActions', () => {
   let flux: FluxFramework;
-  let userActions: userActions;
+  let userActions: UserActions;
 
   beforeEach(() => {
     flux = createMockFlux();
@@ -782,7 +806,7 @@ describe('userActions', () => {
 
   it('should add user with validation', async () => {
     const userData = {username: 'test', email: 'test@example.com'};
-    const result = await userActions.add(userData);
+    const result = await userActions.addUser(userData);
     expect(result).toBeDefined();
   });
 });
@@ -791,7 +815,7 @@ describe('userActions', () => {
 #### Testing with Custom Adapters
 
 ```typescript
-const mockAdapter = jest.fn((input) => ({
+const mockAdapter = vi.fn((input) => ({
   ...input,
   validated: true
 }));
@@ -1267,8 +1291,8 @@ For more detailed examples, see [`examples/permission-system-usage.tsx`](./examp
 ### Prerequisites
 
 - Node.js 16+
-- React 18+
-- TypeScript 4.5+
+- React 19+
+- TypeScript 7+
 
 ### Full Installation
 
@@ -1292,7 +1316,18 @@ Configure your environment-specific settings in the `config` prop of the `Metrop
 
 ## Contributing
 
-We love contributions! Here's how you can help:
+Before opening a pull request, run the same quality gates used for source, tests, examples, and the published declarations:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+`npm run typecheck` checks the production source, unit and integration tests, lint inputs, and every file under `examples/`.
+
+To contribute:
 
 1. **Fork** the repository
 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)

package/docs/ACTIONS.md

@@ -26,6 +26,26 @@ const postActions = createPostActions(flux);
 const restActions = createRestActions(flux);
 ```
 
+### Typed Consolidated Factories
+
+The consolidated factories preserve the selected action types without casts:
+
+```ts
+import {createAction, createActions, createAllActions} from '@nlabs/metropolisjs';
+
+const userActions = createAction('user', flux);
+await userActions.addUser({username: 'ada'});
+
+const actions = createActions(['user', 'post', 'message'], flux);
+await actions.post.add({content: 'Hello!'});
+await actions.message.sendMessage({content: 'Welcome!'});
+
+const allActions = createAllActions(flux);
+await allActions.permission.list();
+```
+
+`createAction()` maps its key to the corresponding action interface, `createActions()` returns exactly the requested keys, and `createAllActions()` returns the complete exported `ActionMap`.
+
 ## Action Families
 
 Each row links to:
@@ -56,7 +76,7 @@ These action families are available through specialized hooks when present, `use
 | Subscription | `useSubscriptionActions` | `subscription` | `createSubscriptionActions` | `addPlan`, `getPlanByItem`, `addSubscription`, `getSubscriptionByItem`, `getSubscriptionListByUser`, `deleteSubscription` | [subscriptionActions.ts](../src/actions/subscriptionActions/subscriptionActions.ts) |
 | Tag | `useTagActions` | `tag` | `createTagActions` | `addTag`, `addTagToItem`, `getTags`, `updateTag`, `deleteTag`, `deleteTagFromItem` | [tagActions.ts](../src/actions/tagActions/tagActions.ts) |
 | Translation | `useTranslationActions` | `translation` | `createTranslationActions` | `addTranslations`, `getTranslation`, `getTranslations`, `hasTranslation`, `queueTranslationKey`, `processPendingTranslations` | [translationActions.ts](../src/actions/translationActions/translationActions.ts) |
-| User | `useUserActions` | `user` | `createUserActions` | `signIn`, `signUp`, `session`, `refreshSession`, `itemById`, `listByLatest`, `updateUser` | [userActions.ts](../src/actions/userActions/userActions.ts) |
+| User | `useUserActions` | `user` | `createUserActions` | `signIn`, `signUp`, `session`, `createBillingSetupSession`, `completeBillingSetupSession`, `deleteBillingCard`, `itemById`, `updateUser` | [userActions.ts](../src/actions/userActions/userActions.ts) |
 | Video | `useVideoActions` | `video` | `createVideoActions` | `add`, `itemById`, `list`, `update`, `delete` | [videoActions.ts](../src/actions/videoActions/videoActions.ts) |
 | Websocket | `useWebsocketActions` | `websocket` | `createWebsocketActions` | `wsInit`, `wsSend`, `onOpen`, `onReceive`, `onClose`, `onError` | [websocketActions.ts](../src/actions/websocketActions/websocketActions.ts) |
 
@@ -121,6 +141,34 @@ Configure the action through the `Metropolis` provider:
 
 The `Metropolis` provider requests beacon delivery automatically on `pagehide` and when `document.visibilityState` changes to `hidden`. A batch accepted by the Beacon API is not submitted a second time. All RUM delivery remains subject to `enabled`, `respectPrivacySignals`, batching, throttling, deduplication, and event sanitization.
 
+## User Billing Setup Sessions
+
+Use the authenticated user actions to collect a billing method through the hosted setup flow:
+
+```ts
+import {createUserActions} from '@nlabs/metropolisjs';
+
+const userActions = createUserActions(flux);
+const checkoutUrl = await userActions.createBillingSetupSession(
+  'https://app.example.com/settings/billing/complete'
+);
+
+window.location.assign(checkoutUrl);
+```
+
+After the billing provider redirects back, complete the session with its identifier:
+
+```ts
+const user = await userActions.completeBillingSetupSession(
+  setupSessionId,
+  ['stripeCardBrand', 'stripeCardLast4']
+);
+```
+
+`createBillingSetupSession(returnUrl)` validates the return URL and resolves to the hosted checkout URL. `completeBillingSetupSession(sessionId, userProps?, requestOptions?)` validates the identifier, returns the updated user, synchronizes the active session when it belongs to that user, dispatches `USER_UPDATE_ITEM_SUCCESS`, and clears related request caches. `deleteBillingCard(userProps?, requestOptions?)` removes the stored method through the same authenticated action family.
+
+These APIs exchange setup-session identifiers and sanitized billing metadata only. They do not accept raw card details.
+
 ## REST Actions
 
 Use REST actions for external APIs that are not represented in Reaktor. REST actions delegate to `@nlabs/rip-hunter`, share Metropolis network/session handling, and can target either a configured endpoint key or an absolute URL.
@@ -173,6 +221,18 @@ All action creators are re-exported from:
 
 - [src/actions/index.ts](../src/actions/index.ts)
 
+The package root also exports every creator, action interface, `ActionMap`, and the consolidated factory functions.
+
 All specialized hooks are exposed from:
 
 - [src/utils/useMetropolis.ts](../src/utils/useMetropolis.ts)
+
+## Development Type Checks
+
+Run the complete TypeScript gate with:
+
+```bash
+npm run typecheck
+```
+
+This validates the production source, tests, lint inputs, and examples. Run `npm run lint`, `npm test`, and `npm run build` before publishing.

package/docs/assets/metropolisjs-mark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 600" role="img" aria-labelledby="title desc">
+  <title id="title">MetropolisJS</title>
+  <desc id="desc">Purple winged V mark representing the connection between frontend and backend systems.</desc>
+  <path
+    d="M600 280C585 280 575 270 565 250C525 170 480 100 415 70C318 25 205 60 125 155C82 206 55 278 40 340C95 250 170 205 245 205C365 205 470 360 555 505C570 532 582 548 600 548C618 548 630 532 645 505C730 360 835 205 955 205C1030 205 1105 250 1160 340C1145 278 1118 206 1075 155C995 60 882 25 785 70C720 100 675 170 635 250C625 270 615 280 600 280Z"
+    fill="#712CF9"/>
+</svg>

package/examples/crud-usage.tsx

@@ -700,7 +700,7 @@ export const EventManagerExample = () => {
             <p>
               {new Date(event.startDate!).toLocaleString()} - {new Date(event.endDate!).toLocaleString()}
             </p>
-            <p>Location: {event.location}</p>
+            <p>Location: {typeof event.location === 'string' ? event.location : event.location?.address}</p>
             <button onClick={() => handleDeleteEvent(event.eventId!)}>Delete</button>
           </div>
         ))}

package/examples/factory-pattern-usage.ts

@@ -1,27 +1,33 @@
 /**
  * Example: Using the Factory Pattern in MetropolisJS
- * 
+ *
  * This file demonstrates how to use the new consolidated action factory
  * instead of individual createXxxActions functions.
  */
 
-import type { FluxFramework } from '@nlabs/arkhamjs';
-import { createAction, createActions, createAllActions } from '../src/utils/actionFactory';
+import {createAction, createActions, createAllActions} from '../src/utils/actionFactory.js';
+
+import type {FluxFramework} from '@nlabs/arkhamjs';
+import type {PostType} from '../src/adapters/postAdapter/postAdapter.js';
+import type {User} from '../src/adapters/userAdapter/userAdapter.js';
+
+const getErrorMessage = (error: unknown): string => (
+  error instanceof Error ? error.message : 'An unknown error occurred'
+);
 
 // Example 1: Basic Usage
 export const basicUsage = (flux: FluxFramework) => {
   // Create actions using consolidated factory functions
-  const userActions = createAction('user', flux) as any;
-  const postActions = createAction('post', flux) as any;
-  const eventActions = createAction('event', flux) as any;
+  const userActions = createAction('user', flux);
+  const postActions = createAction('post', flux);
 
   // Use actions normally
   const addUser = async () => {
-    const user = await userActions.add({
-      username: 'john_doe',
+    const user = await userActions.addUser({
       email: 'john@example.com',
       firstName: 'John',
-      lastName: 'Doe'
+      lastName: 'Doe',
+      username: 'john_doe'
     });
     return user;
   };
@@ -40,20 +46,21 @@ export const basicUsage = (flux: FluxFramework) => {
 // Example 2: Custom Adapter with Business Logic
 export const customAdapterUsage = (flux: FluxFramework) => {
   // Custom user adapter that adds business logic
-  const businessUserAdapter = (input: unknown, options?: any) => {
-    const user = input as any;
-    
+  const businessUserAdapter = (input: unknown): User => {
+    const user = input as User;
+    const email = user.email || '';
+
     // Business validation
-    if (user.email && !user.email.includes('@company.com')) {
+    if(email && !email.includes('@company.com')) {
       throw new Error('Only company emails are allowed');
     }
-    
+
     // Add computed fields
     return {
       ...user,
+      department: email.split('@')[0]?.split('.')[1] || 'general',
       fullName: `${user.firstName || ''} ${user.lastName || ''}`.trim(),
-      isAdmin: user.userAccess >= 3,
-      department: user.email?.split('@')[0]?.split('.')[1] || 'general'
+      isAdmin: (user.userAccess || 0) >= 3
     };
   };
 
@@ -61,8 +68,8 @@ export const customAdapterUsage = (flux: FluxFramework) => {
   const userActions = createAction('user', flux, {
     userAdapter: businessUserAdapter,
     userAdapterOptions: {
-      strict: true,
-      environment: 'production'
+      environment: 'production',
+      strict: true
     }
   });
 
@@ -71,73 +78,72 @@ export const customAdapterUsage = (flux: FluxFramework) => {
 
 // Example 3: Runtime Adapter Updates
 export const runtimeUpdates = (flux: FluxFramework) => {
-  const userActions = createAction('user', flux) as any;
+  const userActions = createAction('user', flux);
 
   // Update adapter at runtime
   const updateToStrictMode = () => {
     userActions.updateUserAdapterOptions({
-      strict: true,
-      environment: 'production'
+      environment: 'production',
+      strict: true
     });
   };
 
   // Add custom validation at runtime
   const addCustomValidation = () => {
-    userActions.updateUserAdapter((input, options) => {
-      const user = input as any;
-      
+    userActions.updateUserAdapter((input) => {
+      const user = input as User;
+
       // Additional runtime validation
-      if (user.age && user.age < 18) {
+      if(user.age && user.age < 18) {
         throw new Error('User must be 18 or older');
       }
-      
+
       return user;
     });
   };
 
-  return {updateToStrictMode, addCustomValidation, userActions};
+  return {addCustomValidation, updateToStrictMode, userActions};
 };
 
 // Example 4: Testing with Mock Adapters
 export const testingExample = (flux: FluxFramework) => {
   // Mock adapter for testing
-  const mockUserAdapter = Object.assign((input: unknown) => {
-    mockUserAdapter.calls.push(input);
+  const calls: unknown[] = [];
+  const mockUserAdapter = (input: unknown) => {
+    calls.push(input);
     return {
       ...(input as Record<string, unknown>),
       id: 'mock-user-id',
-      validated: true,
-      timestamp: new Date().toISOString()
+      timestamp: new Date().toISOString(),
+      validated: true
     };
-  }, {
-    calls: [] as unknown[]
-  });
+  };
 
   const userActions = createAction('user', flux, {
     userAdapter: mockUserAdapter
-  }) as any;
+  });
 
   // Test that adapter was called
   const testUserCreation = async () => {
-    const user = await userActions.add({
-      username: 'test_user',
-      email: 'test@example.com'
+    const user = await userActions.addUser({
+      email: 'test@example.com',
+      username: 'test_user'
     });
 
-    if(mockUserAdapter.calls.length === 0 || user.id !== 'mock-user-id' || user.validated !== true) {
+    if(calls.length === 0 || user.id !== 'mock-user-id' || user.validated !== true) {
       throw new Error('Mock adapter validation failed');
     }
   };
 
-  return {userActions, testUserCreation};
+  return {testUserCreation, userActions};
 };
 
 // Example 5: Multiple Adapters with Different Configurations
 export const multipleAdapters = (flux: FluxFramework) => {
   // User adapter with strict validation
   const strictUserAdapter = (input: unknown) => {
-    const user = input as any;
-    if (!user.username || !user.email) {
+    const user = input as User;
+    if(!user.username || !user.email) {
       throw new Error('Username and email are required');
     }
     return user;
@@ -145,8 +151,8 @@ export const multipleAdapters = (flux: FluxFramework) => {
 
   // Post adapter with content validation
   const contentPostAdapter = (input: unknown) => {
-    const post = input as any;
-    if (post.content && post.content.length > 1000) {
+    const post = input as PostType;
+    if(post.content && post.content.length > 1000) {
       throw new Error('Post content too long');
     }
     return post;
@@ -156,44 +162,44 @@ export const multipleAdapters = (flux: FluxFramework) => {
   const userActions = createAction('user', flux, {
     userAdapter: strictUserAdapter,
     userAdapterOptions: {strict: true}
-  }) as any;
+  });
 
   const postActions = createAction('post', flux, {
     postAdapter: contentPostAdapter,
     postAdapterOptions: {environment: 'development'}
-  }) as any;
+  });
 
-  return {userActions, postActions};
+  return {postActions, userActions};
 };
 
 // Example 6: Error Handling
 export const errorHandling = (flux: FluxFramework) => {
   const userActions = createAction('user', flux, {
     userAdapterOptions: {
-      strict: true,
       customValidation: (input) => {
-        const user = input as any;
-        
+        const user = input as User;
+
         // Custom error handling
-        if (user.username && user.username.length < 3) {
+        if(user.username && user.username.length < 3) {
           throw new Error('Username must be at least 3 characters');
         }
-        
-        if (user.email && !user.email.includes('@')) {
+
+        if(user.email && !user.email.includes('@')) {
           throw new Error('Invalid email format');
         }
-        
+
         return user;
-      }
+      },
+      strict: true
     }
-  }) as any;
+  });
 
-  const createUserWithErrorHandling = async (userData: any) => {
+  const createUserWithErrorHandling = async (userData: Partial<User>) => {
     try {
-      const user = await userActions.add(userData);
+      const user = await userActions.addUser(userData);
       return {success: true, user};
-    } catch (error) {
-      return {success: false, error: error.message};
+    } catch(error) {
+      return {error: getErrorMessage(error), success: false};
     }
   };
 
@@ -204,45 +210,46 @@ export const errorHandling = (flux: FluxFramework) => {
 export const multipleActionsExample = (flux: FluxFramework) => {
   // Create multiple actions at once
   const actions = createActions(['user', 'post', 'message'], flux, {
-    user: {
-      userAdapterOptions: { strict: true }
-    },
     post: {
-      postAdapter: (input: any) => {
-        if (input.content && input.content.length > 1000) {
+      postAdapter: (input: unknown) => {
+        const post = input as PostType;
+        if(post.content && post.content.length > 1000) {
           throw new Error('Post content too long');
         }
-        return input;
+        return post;
       }
+    },
+    user: {
+      userAdapterOptions: {strict: true}
     }
   });
 
-  const createUserAndPost = async (userData: any, postData: any) => {
-    const user = await actions.user.add(userData);
+  const createUserAndPost = async (userData: Partial<User>, postData: Partial<PostType>) => {
+    const user = await actions.user.addUser(userData);
     const post = await actions.post.add({
       ...postData,
       userId: user.userId
     });
-    return { user, post };
+    return {post, user};
   };
 
-  return { actions, createUserAndPost };
+  return {actions, createUserAndPost};
 };
 
 // Example 8: All Actions Creation
 export const allActionsExample = (flux: FluxFramework) => {
   // Create all available actions
   const allActions = createAllActions(flux, {
-    user: { userAdapterOptions: { strict: true } },
-    post: { postAdapterOptions: { environment: 'production' } },
-    image: { imageAdapterOptions: { allowPartial: true } }
+    image: {imageAdapterOptions: {allowPartial: true}},
+    post: {postAdapterOptions: {environment: 'production'}},
+    user: {userAdapterOptions: {strict: true}}
   });
 
   const comprehensiveWorkflow = async () => {
     // Create user
-    const user = await allActions.user.add({
-      username: 'jane_doe',
-      email: 'jane@example.com'
+    const user = await allActions.user.addUser({
+      email: 'jane@example.com',
+      username: 'jane_doe'
     });
 
     // Create post
@@ -263,8 +270,8 @@ export const allActionsExample = (flux: FluxFramework) => {
       recipientId: user.userId
     });
 
-    return { user, post, image };
+    return {image, post, user};
   };
 
-  return { allActions, comprehensiveWorkflow };
+  return {allActions, comprehensiveWorkflow};
 };