@nlabs/metropolisjs 0.3.4 → 0.3.6

package/.github/copilot-instructions.md

@@ -1,167 +1,55 @@
-# MetropolisJS AI Coding Assistant Instructions
-
-## Project Overview
-MetropolisJS is a React library that provides seamless frontend-backend integration for applications using Reaktor backend services and ArkhamJS state management. It handles authentication, real-time messaging, content management, and social features through a unified API.
-
-## Architecture Patterns
-
-### Core Components
-- **Stores**: ArkhamJS-based state management with domain-specific stores (`users`, `posts`, `messages`, etc.)
-- **Actions**: Factory function pattern using `createUserActions(flux)`, `createPostActions(flux)`, etc.
-- **Adapters**: Zod-validated data parsers for API responses (`parseUser`, `parsePost`, etc.)
-- **Configuration**: Environment-specific config objects with API endpoints, WebSocket URLs, and session settings
-
-### Key Conventions
-
-#### 1. Action Creation Pattern
-```typescript
-// Correct: Use factory functions
-import {createUserActions} from '@nlabs/metropolisjs';
-const userActions = createUserActions(flux);
-
-// Avoid: Direct instantiation
-const userActions = new UserActions(flux);
-```
-
-#### 2. GraphQL Mutation Structure
-All GraphQL mutations are wrapped in domain fields:
-```graphql
-mutation UsersSignIn($user: UserInput!, $expires: Int) {
-  users {
-    signIn(user: $user, expires: $expires) {
-      token
-      expires
-    }
-  }
-}
-```
-
-#### 3. Store Constants Pattern
-Each store defines action type constants:
-```typescript
-export const USER_CONSTANTS = {
-  SIGN_IN_SUCCESS: 'USER_SIGN_IN_SUCCESS',
-  SIGN_IN_ERROR: 'USER_SIGN_IN_ERROR',
-  // ... etc
-};
-```
-
-#### 4. Adapter Validation
-Use Zod schemas for data validation in adapters:
-```typescript
-import {z} from 'zod';
-const userSchema = z.object({
-  id: z.string(),
-  email: z.string().email(),
-  // ...
-});
-```
-
-## Development Workflow
-
-### Build Commands
-- `npm run build` - Compile TypeScript to `lib/` using @nlabs/lex
-- `npm run dev` - Development build with watch mode
-- `npm run test` - Run Jest tests with @nlabs/lex configuration
-- `npm run lint` - ESLint with auto-fix using @nlabs/lex
-
-### Testing Setup
-- Uses Jest with jsdom environment
-- Tests located in `__tests__/` directories alongside source
-- Mock setup in `__mocks__/` for external dependencies
-
-### TypeScript Configuration
-- Strict mode disabled (`"strict": false`)
-- ESNext modules with bundler resolution
-- Declaration files emitted to `lib/` directory
-
-## Coding Conventions
-
-### Comments
-- Do not write comments in code except for TODOs, copyrights, and lint disables
-- Variables and code should be self-explanatory with clear, descriptive names
-- Use meaningful variable names that explain their purpose
-- Structure code to be readable without additional comments
-
-## Integration Points
-
-### External Dependencies
-- **@nlabs/arkhamjs**: State management framework
-- **@nlabs/arkhamjs-utils-react**: React hooks for ArkhamJS
-- **i18next**: Internationalization
-- **sockette**: WebSocket client
-- **zod**: Schema validation
-
-### Real-time Features
-- WebSocket connections via `websocketStore`
-- Server-Sent Events (SSE) for notifications
-- Automatic reconnection and state synchronization
-
-### Authentication Flow
-- Session management through `user.session` state
-- Token refresh via `refreshSession()` API calls
-- Environment-specific auth checks via config
-
-## Code Organization
-
-### Directory Structure
-```
-src/
-├── actions/          # Factory-based action creators
-├── adapters/         # Data parsing and validation
-├── stores/           # ArkhamJS store definitions
-├── config/           # Environment configuration
-├── utils/            # Shared utilities (API, i18n, etc.)
-└── constants/        # Application constants
-```
-
-### File Naming
-- Actions: `userActions.ts`, `postActions.ts`
-- Stores: `userStore.ts`, `postStore.ts`
-- Adapters: `userAdapter.ts`, `postAdapter.ts`
-- Tests: `userActions.test.ts` alongside implementation
-
-## Common Patterns
-
-### Error Handling
-```typescript
-try {
-  const result = await userActions.signIn({username, password});
-  // Handle success
-} catch (error) {
-  // Error dispatched to store with *_ERROR constant
-  console.error('Sign in failed:', error);
-}
-```
-
-### State Access
-```typescript
-import {useFlux} from '@nlabs/arkhamjs-utils-react';
-
-const MyComponent = () => {
-  const flux = useFlux();
-  const user = flux.getState('user.item', {});
-  // ...
-};
-```
-
-### Custom Adapters
-```typescript
-const customUserAdapter = (input: unknown) => {
-  const user = parseUser(input); // Use default parser first
-  // Add custom business logic
-  return {...user, computedField: 'value'};
-};
-
-const userActions = createUserActions(flux, {
-  userAdapter: customUserAdapter
-});
-```
-
-## Key Files to Reference
-- `src/index.tsx` - Main library exports and Metropolis component
-- `src/stores/index.ts` - All store exports
-- `src/actions/index.ts` - All action exports
-- `src/adapters/index.ts` - All adapter exports
-- `src/utils/api.ts` - GraphQL API utilities
-- `factoryPatternGuide.md` - Detailed factory pattern documentation
+# AI Coding Assistant Instructions
+
+## Shared NLabs Stack
+- Use Lex (`@nlabs/lex`) for CLI workflows, building, compiling, deploying, and testing projects.
+- Use Vitest for unit and integration tests.
+- Use Playwright for end-to-end tests.
+- Use GothamJS (`@nlabs/gothamjs`) for the presentation layer. Obtain components, views, routing, Tailwind setup, and default styles from GothamJS before creating custom project-level components.
+- Use React v19 for frontend work.
+- Use Tailwind v4 for CSS styles.
+- Use MetropolisJS (`@nlabs/metropolisjs`) as the starting point for all frontend API integration. Create custom data types, actions, queries, or mutations only after MetropolisJS has been exhausted.
+- Use Rip-Hunter to access API endpoints.
+- Use `fetch` through Rip-Hunter rather than direct project-level `fetch` calls.
+- Use ArkhamJS (`@nlabs/arkhamjs`) as the frontend data store. Store data, including session-storage-backed data, through Flux actions and event listeners.
+- Prefer listening for Flux events over chaining `.then(...)` to Flux action promises.
+- Flux actions update the data store before dispatching their events.
+- Multiple listeners may listen for the same Flux action event.
+- Read persistent data from the data store, and read event-specific data directly from the Flux action event when appropriate.
+- Send all data as JSON.
+- Use Reaktor (`@nlabs/reaktor`) for actions that interact with the ArangoDB database.
+
+## Database
+- All projects use the ArangoDB instance at `https://db.reaktor.io:8529`.
+- ArangoDB is a document NoSQL database with SQL-style query and graph database features.
+- When adding or deleting documents, check whether associated graph edges also need to be added or deleted.
+
+## Project Structure
+- Web apps should contain at least one microsite.
+- Web apps should include a `src/ui` folder.
+- Web apps with a backend should include a `src/api` folder or microsite.
+- Library projects may use a root source folder without `src/ui` or `src/api`.
+- Shared utility/helper functions should live in a shared file when used in more than one place.
+- Keep one component per file.
+- Each component should have a sibling test file named `MyComponent.test.ts` or `MyComponent.test.tsx`.
+- Group components by component folder, for example `src/ui/components/MyComponent/MyComponent.tsx`.
+
+## Package Scripts
+- All projects should have at least `start`, `test`, and `update` scripts.
+- If a project includes both `api` and `ui` workspaces, use `concurrently` in `start`:
+  `"start": "concurrently \"npm run start -w api\" \"npm run start -w ui\""`
+- Use this workspace test script:
+  `"test": "npm run test --workspaces --ignore-scripts"`
+- Use this workspace update script:
+  `"update": "npm run update --workspaces"`
+
+## Testing
+- Maintain at least 90% unit test coverage.
+- Components that require other components should have integration tests.
+- Provide at least one Playwright e2e test for each happy path.
+
+## Code Style
+- Use arrow functions for functions.
+- Correctly type all variables, props, and arguments unless TypeScript inference already provides the correct type.
+- Sort props and object keys alphabetically.
+- Check and fix all ESLint errors and warnings.
+- Use `eslint-config-styleguide` for linting rules.

package/AGENTS.md

@@ -1,13 +1,55 @@
-# AGENTS.md
+# AI Coding Assistant Instructions
 
-## Core Rule
-- Treat shared data contracts as strict and canonical.
-- Do not add legacy aliases, compatibility shims, fallback field names, or dual-write behavior.
+## Shared NLabs Stack
+- Use Lex (`@nlabs/lex`) for CLI workflows, building, compiling, deploying, and testing projects.
+- Use Vitest for unit and integration tests.
+- Use Playwright for end-to-end tests.
+- Use GothamJS (`@nlabs/gothamjs`) for the presentation layer. Obtain components, views, routing, Tailwind setup, and default styles from GothamJS before creating custom project-level components.
+- Use React v19 for frontend work.
+- Use Tailwind v4 for CSS styles.
+- Use MetropolisJS (`@nlabs/metropolisjs`) as the starting point for all frontend API integration. Create custom data types, actions, queries, or mutations only after MetropolisJS has been exhausted.
+- Use Rip-Hunter to access API endpoints.
+- Use `fetch` through Rip-Hunter rather than direct project-level `fetch` calls.
+- Use ArkhamJS (`@nlabs/arkhamjs`) as the frontend data store. Store data, including session-storage-backed data, through Flux actions and event listeners.
+- Prefer listening for Flux events over chaining `.then(...)` to Flux action promises.
+- Flux actions update the data store before dispatching their events.
+- Multiple listeners may listen for the same Flux action event.
+- Read persistent data from the data store, and read event-specific data directly from the Flux action event when appropriate.
+- Send all data as JSON.
+- Use Reaktor (`@nlabs/reaktor`) for actions that interact with the ArangoDB database.
 
-## Required Patterns
-- When a shared contract changes, update MetropolisJS to the canonical field names and update callers instead of supporting both shapes.
-- Keep API payloads aligned with the current Reaktor schema.
+## Database
+- All projects use the ArangoDB instance at `https://db.reaktor.io:8529`.
+- ArangoDB is a document NoSQL database with SQL-style query and graph database features.
+- When adding or deleting documents, check whether associated graph edges also need to be added or deleted.
 
-## Prohibited Patterns
-- No temporary backward-compatibility layers for field renames.
-- No adapters that emit both old and new field names for the same value.
+## Project Structure
+- Web apps should contain at least one microsite.
+- Web apps should include a `src/ui` folder.
+- Web apps with a backend should include a `src/api` folder or microsite.
+- Library projects may use a root source folder without `src/ui` or `src/api`.
+- Shared utility/helper functions should live in a shared file when used in more than one place.
+- Keep one component per file.
+- Each component should have a sibling test file named `MyComponent.test.ts` or `MyComponent.test.tsx`.
+- Group components by component folder, for example `src/ui/components/MyComponent/MyComponent.tsx`.
+
+## Package Scripts
+- All projects should have at least `start`, `test`, and `update` scripts.
+- If a project includes both `api` and `ui` workspaces, use `concurrently` in `start`:
+  `"start": "concurrently \"npm run start -w api\" \"npm run start -w ui\""`
+- Use this workspace test script:
+  `"test": "npm run test --workspaces --ignore-scripts"`
+- Use this workspace update script:
+  `"update": "npm run update --workspaces"`
+
+## Testing
+- Maintain at least 90% unit test coverage.
+- Components that require other components should have integration tests.
+- Provide at least one Playwright e2e test for each happy path.
+
+## Code Style
+- Use arrow functions for functions.
+- Correctly type all variables, props, and arguments unless TypeScript inference already provides the correct type.
+- Sort props and object keys alphabetically.
+- Check and fix all ESLint errors and warnings.
+- Use `eslint-config-styleguide` for linting rules.

package/README.md

@@ -1,5 +1,9 @@
 # MetropolisJS: Seamless Frontend-Backend Integration Framework
 
+<p align="center">
+  <img src="docs/assets/metropolisjs-logo.png" alt="MetropolisJS logo" width="432">
+</p>
+
 > **The Ultimate Frontend Integration Library for Modern Web Applications**
 
 [![npm version](https://img.shields.io/npm/v/@nlabs/metropolisjs.svg?style=flat-square)](https://www.npmjs.com/package/@nlabs/metropolisjs)
@@ -53,7 +57,7 @@ npm install @nlabs/metropolisjs @nlabs/arkhamjs @nlabs/arkhamjs-utils-react
 ### Basic Setup
 
 ```tsx
-import {Metropolis, useUserActions, useMessageActions, useWebsocketActions} from '@nlabs/metropolisjs';
+import {Metropolis, useUserActions, useMessageActions, useRestActions, useWebsocketActions} from '@nlabs/metropolisjs';
 
 const App = () => {
   return (
@@ -92,14 +96,59 @@ MetropolisJS provides multiple ways to access actions:
 // Option 1: Specialized hooks (recommended - best performance)
 const userActions = useUserActions();
 const postActions = usePostActions();
+const restActions = useRestActions();
 
 // Option 2: Selective creation
-const {userActions, postActions} = useMetropolis(['user', 'post']);
+const {userActions, postActions, restActions} = useMetropolis(['user', 'post', 'rest']);
 
 // Option 3: All actions (default behavior)
 const {userActions, postActions, messageActions} = useMetropolis();
 ```
 
+### External REST Endpoints
+
+MetropolisJS includes a `rest` action group for APIs that are not part of Reaktor. It delegates to `@nlabs/rip-hunter`, so app code can keep using Metropolis actions instead of importing rip-hunter directly.
+
+```tsx
+<Metropolis
+  config={{
+    development: {
+      app: {
+        api: {
+          endpoints: {
+            weather: 'https://api.example.com/weather'
+          },
+          public: 'http://localhost:3000/public',
+          url: 'http://localhost:3000/app'
+        }
+      }
+    }
+  }}
+>
+  <YourApp />
+</Metropolis>
+
+const WeatherPanel = () => {
+  const restActions = useRestActions();
+
+  const loadWeather = async () => {
+    const weather = await restActions.get('weather', {zip: '60601'}, {cache: true});
+    return weather;
+  };
+};
+```
+
+Use `authenticate: true` when an external endpoint should receive the current Metropolis session token:
+
+```tsx
+const profile = await restActions.request(
+  'https://api.example.com/profile',
+  'PATCH',
+  {displayName: 'Ada'},
+  {authenticate: true}
+);
+```
+
 ## Configuration
 
 The `Metropolis` component accepts three main props: `config`, `adapters`, and `translations`. Here's how to configure each:
@@ -165,6 +214,7 @@ The `config` prop accepts a `MetropolisConfiguration` object that supports envir
 - `environment`: `'development' | 'production' | 'test' | 'local'` - Current environment
 - `app`: Application-specific configuration
   - `api`: API endpoint configuration
+    - `endpoints`: Named external REST endpoints for `restActions`
     - `url`: Main API endpoint
     - `public`: Public API endpoint
     - `uploadImage`: Image upload endpoint

package/docs/ACTIONS.md

@@ -7,20 +7,22 @@ This reference documents every action family exposed by MetropolisJS, how to acc
 Use specialized hooks in React components:
 
 ```tsx
-import {useUserActions, usePostActions, useMessageActions} from '@nlabs/metropolisjs';
+import {useUserActions, usePostActions, useMessageActions, useRestActions} from '@nlabs/metropolisjs';
 
 const userActions = useUserActions();
 const postActions = usePostActions();
 const messageActions = useMessageActions();
+const restActions = useRestActions();
 ```
 
 Or create actions directly with a Flux instance:
 
 ```ts
-import {createUserActions, createPostActions} from '@nlabs/metropolisjs';
+import {createUserActions, createPostActions, createRestActions} from '@nlabs/metropolisjs';
 
 const userActions = createUserActions(flux);
 const postActions = createPostActions(flux);
+const restActions = createRestActions(flux);
 ```
 
 ## Action Families
@@ -30,27 +32,87 @@ Each row links to:
 - hook exposure (`src/utils/useMetropolis.ts`)
 - common method names (full signatures live in the interface in each source file)
 
-| Family | Hook | Creator | Typical Methods | Source |
+### Hook and Factory Actions
+
+These action families are available through specialized hooks when present, `useMetropolis([...])`, `createAction(...)`, `createActions(...)`, and direct creators.
+
+| Family | Hook | Factory Key | Creator | Typical Methods | Source |
 | --- | --- | --- | --- | --- |
-| App | `useMetropolis(['app'])` | `createAppActions` | `add`, `itemById`, `list`, `update`, `delete` | [appActions.ts](../src/actions/appActions/appActions.ts) |
-| Connection | `useMetropolis(['connection'])` | `createConnectionActions` | `addConnection`, `getConnections`, `removeConnection` | [connectionActions.ts](../src/actions/connectionActions/connectionActions.ts) |
-| Content | `useContentActions` | `createContentActions` | `add`, `itemById`, `itemByKey`, `listByCategory`, `list`, `update`, `delete` | [contentActions.ts](../src/actions/contentActions/contentActions.ts) |
-| Conversation | `useMetropolis(['conversation'])` | `createConversationActions` | `add`, `itemById`, `list`, `update`, `delete` | [conversationActions.ts](../src/actions/conversationActions/conversationActions.ts) |
-| Event | `useEventActions` | `createEventActions` | `addEvent`, `getEvent`, `getEventsByTags`, `getEventsByReactions`, `updateEvent`, `deleteEvent` | [eventActions.ts](../src/actions/eventActions/eventActions.ts) |
-| Group | `useGroupActions` | `createGroupActions` | `add`, `itemById`, `listByLatest`, `update`, `delete` | [groupActions.ts](../src/actions/groupActions/groupActions.ts) |
-| Image | `useImageActions` | `createImageActions` | `add`, `update`, `delete`, `upload`, `countByItem`, `listByItem`, `listByReactions` | [imageActions.ts](../src/actions/imageActions/imageActions.ts) |
-| Location | `useLocationActions` | `createLocationActions` | `autocompleteLocation`, `add`, `getLocation`, `getCurrentLocation`, `listByItem`, `update`, `delete` | [locationActions.ts](../src/actions/locationActions/locationActions.ts) |
-| Message | `useMessageActions` | `createMessageActions` | `sendMessage`, `getMessages`, `getConversations`, `getDirectConversation` | [messageActions.ts](../src/actions/messageActions/messageActions.ts) |
-| Permission | `usePermissionActions` | `createPermissionActions` | `add`, `check`, `itemById`, `list`, `listByUser`, `update`, `remove` | [permissionActions.ts](../src/actions/permissionActions/permissionActions.ts) |
-| Post | `usePostActions` | `createPostActions` | `add`, `itemById`, `listByLatest`, `listByLocation`, `listByReactions`, `listByTags`, `update`, `delete` | [postActions.ts](../src/actions/postActions/postActions.ts) |
-| Persona | `usePersonaActions` | `createPersonaActions` | `addPersona`, `getPersona`, `getPersonas`, `updatePersona`, `deletePersona` | [personaActions.ts](../src/actions/personaActions/personaActions.ts) |
-| Reaction | `useReactionActions` | `createReactionActions` | `addReaction`, `deleteReaction`, `getReactionCount`, `hasReaction`, `abbreviateCount` | [reactionActions.ts](../src/actions/reactionActions/reactionActions.ts) |
-| SSE | `useMetropolis(['sse'])` | `createSSEActions` | `connect`, `disconnect`, `reconnect`, `isConnected`, `sendMessage`, `addEventListener`, `removeEventListener` | [sseActions.ts](../src/actions/sseActions/sseActions.ts) |
-| Tag | `useTagActions` | `createTagActions` | `addTag`, `addTagToItem`, `getTags`, `updateTag`, `deleteTag`, `deleteTagFromItem` | [tagActions.ts](../src/actions/tagActions/tagActions.ts) |
-| Translation | `useTranslationActions` | `createTranslationActions` | `addTranslations`, `getTranslation`, `getTranslations`, `hasTranslation`, `queueTranslationKey`, `processPendingTranslations` | [translationActions.ts](../src/actions/translationActions/translationActions.ts) |
-| User | `useUserActions` | `createUserActions` | `signIn`, `signUp`, `session`, `refreshSession`, `itemById`, `listByLatest`, `updateUser` | [userActions.ts](../src/actions/userActions/userActions.ts) |
-| Video | `useMetropolis(['video'])` | `createVideoActions` | `add`, `itemById`, `list`, `update`, `delete` | [videoActions.ts](../src/actions/videoActions/videoActions.ts) |
-| Websocket | `useWebsocketActions` | `createWebsocketActions` | `wsInit`, `wsSend`, `onOpen`, `onReceive`, `onClose`, `onError` | [websocketActions.ts](../src/actions/websocketActions/websocketActions.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) |
+| Group | `useGroupActions` | `group` | `createGroupActions` | `add`, `itemById`, `listByLatest`, `update`, `delete` | [groupActions.ts](../src/actions/groupActions/groupActions.ts) |
+| Image | `useImageActions` | `image` | `createImageActions` | `add`, `update`, `delete`, `upload`, `countByItem`, `listByItem`, `listByReactions` | [imageActions.ts](../src/actions/imageActions/imageActions.ts) |
+| Location | `useLocationActions` | `location` | `createLocationActions` | `autocompleteLocation`, `add`, `getLocation`, `getCurrentLocation`, `listByItem`, `update`, `delete` | [locationActions.ts](../src/actions/locationActions/locationActions.ts) |
+| Message | `useMessageActions` | `message` | `createMessageActions` | `sendMessage`, `getMessages`, `getConversations`, `getDirectConversation` | [messageActions.ts](../src/actions/messageActions/messageActions.ts) |
+| Permission | `usePermissionActions` | `permission` | `createPermissionActions` | `add`, `check`, `itemById`, `list`, `listByUser`, `update`, `remove` | [permissionActions.ts](../src/actions/permissionActions/permissionActions.ts) |
+| Post | `usePostActions` | `post` | `createPostActions` | `add`, `itemById`, `listByLatest`, `listByLocation`, `listByReactions`, `listByTags`, `update`, `delete` | [postActions.ts](../src/actions/postActions/postActions.ts) |
+| Persona | `usePersonaActions` | `persona` | `createPersonaActions` | `addPersona`, `getPersona`, `getPersonas`, `updatePersona`, `deletePersona` | [personaActions.ts](../src/actions/personaActions/personaActions.ts) |
+| Reaction | `useReactionActions` | `reaction` | `createReactionActions` | `addReaction`, `deleteReaction`, `getReactionCount`, `hasReaction`, `abbreviateCount` | [reactionActions.ts](../src/actions/reactionActions/reactionActions.ts) |
+| REST | `useRestActions` | `rest` | `createRestActions` | `get`, `post`, `put`, `delete`, `request` | [restActions.ts](../src/actions/restActions/restActions.ts) |
+| SSE | `useMetropolis(['sse'])` | `sse` | `createSSEActions` | `connect`, `disconnect`, `reconnect`, `isConnected`, `sendMessage`, `addEventListener`, `removeEventListener` | [sseActions.ts](../src/actions/sseActions/sseActions.ts) |
+| 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) |
+| 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) |
+
+### Direct Creator Actions
+
+These creators are exported directly from MetropolisJS, but are not currently part of the `createAction(...)`/`useMetropolis([...])` factory key union.
+
+| Family | Creator | Typical Methods | Source |
+| --- | --- | --- | --- |
+| App | `createAppActions` | `add`, `itemById`, `list`, `update`, `delete` | [appActions.ts](../src/actions/appActions/appActions.ts) |
+| 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) |
+
+## 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.
+
+Configure named endpoints under `app.api.endpoints`:
+
+```tsx
+<Metropolis
+  config={{
+    development: {
+      app: {
+        api: {
+          endpoints: {
+            weather: 'https://api.example.com/weather'
+          },
+          public: 'http://localhost:3000/public',
+          url: 'http://localhost:3000/app'
+        }
+      }
+    }
+  }}
+>
+  <YourApp />
+</Metropolis>
+```
+
+Call the endpoint through `useRestActions()`:
+
+```ts
+const restActions = useRestActions();
+
+const weather = await restActions.get('weather', {zip: '60601'}, {cache: true});
+const created = await restActions.post('https://api.example.com/items', {name: 'Item'});
+```
+
+Pass `authenticate: true` only when the endpoint should receive the current Metropolis session token:
+
+```ts
+const profile = await restActions.request(
+  'https://api.example.com/profile',
+  'PATCH',
+  {displayName: 'Ada'},
+  {authenticate: true}
+);
+```
 
 ## Full Exports
 

package/examples/factory-pattern-usage.ts

@@ -101,12 +101,17 @@ export const runtimeUpdates = (flux: FluxFramework) => {
 // Example 4: Testing with Mock Adapters
 export const testingExample = (flux: FluxFramework) => {
   // Mock adapter for testing
-  const mockUserAdapter = jest.fn((input: unknown) => ({
-    ...(input as Record<string, unknown>),
-    id: 'mock-user-id',
-    validated: true,
-    timestamp: new Date().toISOString()
-  }));
+  const mockUserAdapter = Object.assign((input: unknown) => {
+    mockUserAdapter.calls.push(input);
+    return {
+      ...(input as Record<string, unknown>),
+      id: 'mock-user-id',
+      validated: true,
+      timestamp: new Date().toISOString()
+    };
+  }, {
+    calls: [] as unknown[]
+  });
 
   const userActions = createAction('user', flux, {
     userAdapter: mockUserAdapter
@@ -119,9 +124,9 @@ export const testingExample = (flux: FluxFramework) => {
       email: 'test@example.com'
     });
 
-    expect(mockUserAdapter).toHaveBeenCalled();
-    expect(user.id).toBe('mock-user-id');
-    expect(user.validated).toBe(true);
+    if(mockUserAdapter.calls.length === 0 || user.id !== 'mock-user-id' || user.validated !== true) {
+      throw new Error('Mock adapter validation failed');
+    }
   };
 
   return {userActions, testUserCreation};
@@ -280,4 +285,4 @@ export const migrationExample = (flux: FluxFramework) => {
   };
 
   return { createUser, createPost };
-}; 
+}; 

package/lex.config.mjs

@@ -12,13 +12,6 @@ export default Config.create({
     minify: process.env.NODE_ENV === 'production'
   },
   gitUrl: 'https://github.com/nitrogenlabs/metropolisjs',
-  jest: {
-    extensionsToTreatAsEsm: ['.ts', '.tsx'],
-    moduleNameMapper: {
-      '^@nlabs/(.*)$': '<rootDir>/node_modules/@nlabs/$1'
-    },
-    testEnvironment: 'jsdom'
-  },
   outputPath: 'lib',
   targetEnvironment: 'web',
   useESM: true,
@@ -53,6 +46,10 @@ export default Config.create({
         lines: 90,
         statements: 90
       }
-    }
+    },
+    globals: true,
+    hookTimeout: 120000,
+    testEnvironment: 'jsdom',
+    testTimeout: 120000
   }
 });

package/lib/actions/appActions/appActions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appActions.d.ts","sourceRoot":"","sources":["../../../src/actions/appActions/appActions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,6BAA6B,CAAC;AAItE,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,GAAG,CAAC;IAClE,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE;QACJ,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxG,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1G,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACrH,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChH,gBAAgB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,GAAG,KAAK,IAAI,CAAC;IAC1F,uBAAuB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/D;AAKD,eAAO,MAAM,gBAAgB,GAC3B,MAAM,aAAa,EACnB,UAAU,iBAAiB,KAC1B,UAyLF,CAAC"}
+{"version":3,"file":"appActions.d.ts","sourceRoot":"","sources":["../../../src/actions/appActions/appActions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,6BAA6B,CAAC;AAItE,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,GAAG,CAAC;IAClE,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE;QACJ,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxG,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1G,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACrH,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChH,gBAAgB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,GAAG,KAAK,IAAI,CAAC;IAC1F,uBAAuB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/D;AAKD,eAAO,MAAM,gBAAgB,GAC3B,MAAM,aAAa,EACnB,UAAU,iBAAiB,KAC1B,UAuNF,CAAC"}