@nlabs/metropolisjs 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.0.7
+
+- Flush pending RUM analytics with the Beacon API when a page is hidden or unloaded.
+- Fall back to the normal unauthenticated RUM request when beacon delivery is unavailable or declined.
+- Expose `flush({useBeacon: true})` and `rumBeaconRequest(...)` for explicit terminal delivery.
+- Document RUM endpoint configuration, beacon lifecycle behavior, fallback semantics, and `useAwsRum()` usage.
+
 ## 1.0.3
 
 - Send the public RUM `analyticsId` to Reaktor in the JSON mutation payload.

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**
@@ -155,7 +155,7 @@ The `Metropolis` component accepts three main props: `config`, `adapters`, and `
 
 ### RUM analytics
 
-Configure the public analytics identifier returned by Reaktor under `app.rum.analyticsId`. MetropolisJS sends it in the JSON `RumBatchInput.analyticsId` field; it is not placed in a URL or request header.
+Configure the public analytics identifier returned by Reaktor under `app.rum.analyticsId` and the collection endpoint under `app.api.endpoints.rum`. MetropolisJS sends the identifier in the JSON batch body; it is not placed in the URL or an authorization header.
 
 ```tsx
 <Metropolis
@@ -163,9 +163,18 @@ Configure the public analytics identifier returned by Reaktor under `app.rum.ana
     production: {
       app: {
         name: 'My App',
+        api: {
+          endpoints: {
+            rum: 'https://events.example.com/track'
+          }
+        },
         rum: {
           analyticsId: '00000000-0000-4000-8000-000000000000',
-          enabled: true
+          debounceMs: 250,
+          dedupeMs: 1000,
+          enabled: true,
+          respectPrivacySignals: true,
+          throttleMs: 1000
         }
       }
     }
@@ -174,7 +183,47 @@ Configure the public analytics identifier returned by Reaktor under `app.rum.ana
 </Metropolis>
 ```
 
-`app.rum.analyticsId` is the identifier sent with each analytics batch.
+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
+
+When the page is hidden or receives `pagehide`, the `Metropolis` provider automatically flushes pending RUM events with `navigator.sendBeacon()`. This gives terminal analytics a chance to finish without delaying navigation or page shutdown.
+
+Beacon delivery is best-effort:
+
+- If `navigator.sendBeacon` is unavailable, throws, or declines the payload, MetropolisJS immediately falls back to its normal asynchronous RUM request.
+- A batch accepted by `sendBeacon` is not sent again through the normal request path.
+- Scheduled and explicit `flush()` calls continue to use the normal request path unless `useBeacon` is requested.
+- Privacy signals and the `enabled` option are respected for both delivery paths.
+
+Use the specialized hook when an application needs to track or flush events directly:
+
+```tsx
+import {useAwsRum} from '@nlabs/metropolisjs';
+
+const SaveButton = () => {
+  const rum = useAwsRum();
+
+  const onSave = () => {
+    rum.track({
+      name: 'settings_saved',
+      path: '/settings',
+      properties: {section: 'profile'},
+      type: 'click'
+    });
+  };
+
+  return <button onClick={onSave}>Save</button>;
+};
+```
+
+For an application-controlled terminal flush, request beacon delivery explicitly:
+
+```ts
+await rum.flush({useBeacon: true});
+```
+
+Calling `flush({useBeacon: true})` is safe in non-browser environments and older browsers because it falls back to the normal RUM request when the Beacon API cannot be used.
 
 ### Configuration Object
 
@@ -401,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);
@@ -427,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
@@ -505,6 +589,7 @@ MetropolisJS provides comprehensive actions for all your needs. Access them usin
 
 ### Specialized Hooks (Recommended)
 
+- `useAwsRum()` - Analytics tracking, batching, and terminal beacon delivery
 - `useUserActions()` - Authentication, personas, user management
 - `useMessageActions()` - Real-time messaging and conversations
 - `usePermissionActions()` - Permission and role management (RBAC)
@@ -547,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')) {
@@ -572,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
   };
 };
 
@@ -638,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:
 
@@ -715,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();
@@ -732,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();
   });
 });
@@ -741,7 +815,7 @@ describe('userActions', () => {
 #### Testing with Custom Adapters
 
 ```typescript
-const mockAdapter = jest.fn((input) => ({
+const mockAdapter = vi.fn((input) => ({
   ...input,
   validated: true
 }));
@@ -1217,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
 
@@ -1242,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`)
@@ -1256,6 +1341,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Additional Documentation
 
+- **[Actions Reference](./docs/ACTIONS.md)** - Action families, hooks, factories, and RUM beacon delivery
 - **[Factory Pattern Guide](./factoryPatternGuide.md)** - Detailed guide on using the factory pattern
 - **[Architecture Analysis](./ARCHITECTURE_ANALYSIS.md)** - Deep dive into the architecture
 - **[Changelog](./CHANGELOG.md)** - Complete list of changes and improvements

package/docs/ACTIONS.md

@@ -7,8 +7,9 @@ This reference documents every action family exposed by MetropolisJS, how to acc
 Use specialized hooks in React components:
 
 ```tsx
-import {useUserActions, usePostActions, useMessageActions, useRestActions} from '@nlabs/metropolisjs';
+import {useAwsRum, useUserActions, usePostActions, useMessageActions, useRestActions} from '@nlabs/metropolisjs';
 
+const rum = useAwsRum();
 const userActions = useUserActions();
 const postActions = usePostActions();
 const messageActions = useMessageActions();
@@ -25,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:
@@ -37,7 +58,8 @@ Each row links to:
 These action families are available through specialized hooks when present, `useMetropolis([...])`, `createAction(...)`, `createActions(...)`, and direct creators.
 
 | Family | Hook | Factory Key | Creator | Typical Methods | Source |
-| --- | --- | --- | --- | --- |
+| --- | --- | --- | --- | --- | --- |
+| AWS RUM | `useAwsRum` | `awsRum` | `createAwsRumActions` | `track`, `flush`, `destroy` | [awsRumActions.ts](../src/actions/awsRumActions/awsRumActions.ts) |
 | Content | `useContentActions` | `content` | `createContentActions` | `add`, `itemById`, `itemByKey`, `listByCategory`, `list`, `update`, `delete` | [contentActions.ts](../src/actions/contentActions/contentActions.ts) |
 | CRM | `useCrmActions` | `crm` | `createCrmActions` | `mailingLists`, `createMailingList`, `createSupportTicket`, `supportTickets`, `customerOrdersByUser` | [crmActions.ts](../src/actions/crmActions/crmActions.ts) |
 | Event | `useEventActions` | `event` | `createEventActions` | `addEvent`, `getEvent`, `getEventsByTags`, `getEventsByReactions`, `updateEvent`, `deleteEvent` | [eventActions.ts](../src/actions/eventActions/eventActions.ts) |
@@ -54,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) |
 
@@ -68,6 +90,85 @@ These creators are exported directly from MetropolisJS, but are not currently pa
 | Connection | `createConnectionActions` | `addConnection`, `getConnections`, `removeConnection` | [connectionActions.ts](../src/actions/connectionActions/connectionActions.ts) |
 | Conversation | `createConversationActions` | `add`, `itemById`, `list`, `update`, `delete` | [conversationActions.ts](../src/actions/conversationActions/conversationActions.ts) |
 
+## AWS RUM Actions
+
+Use `useAwsRum()` to queue sanitized analytics events and flush them to the configured RUM endpoint:
+
+```tsx
+import {useAwsRum} from '@nlabs/metropolisjs';
+
+const AnalyticsExample = () => {
+  const rum = useAwsRum();
+
+  const trackCheckout = () => {
+    rum.track({
+      name: 'checkout_started',
+      path: '/checkout',
+      properties: {source: 'cart'},
+      type: 'click'
+    });
+  };
+
+  return <button onClick={trackCheckout}>Checkout</button>;
+};
+```
+
+Configure the action through the `Metropolis` provider:
+
+```tsx
+<Metropolis
+  config={{
+    production: {
+      app: {
+        api: {
+          endpoints: {
+            rum: 'https://events.example.com/track'
+          }
+        },
+        rum: {
+          analyticsId: 'my-public-analytics-id',
+          enabled: true
+        }
+      }
+    }
+  }}
+>
+  <App />
+</Metropolis>
+```
+
+`flush()` uses the normal asynchronous request path. `flush({useBeacon: true})` first asks the browser to queue the JSON batch with `navigator.sendBeacon()`, then falls back to the normal request if the Beacon API is unavailable or declines the payload.
+
+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.
@@ -120,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>
         ))}