@nlabs/metropolisjs 0.1.1 → 0.2.0

package/.github/copilot-instructions.md

@@ -0,0 +1,167 @@
+# 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

package/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS.md
+
+## Core Rule
+- Treat shared data contracts as strict and canonical.
+- Do not add legacy aliases, compatibility shims, fallback field names, or dual-write behavior.
+
+## 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.
+
+## Prohibited Patterns
+- No temporary backward-compatibility layers for field renames.
+- No adapters that emit both old and new field names for the same value.

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+## Architecture Modernization (2025)
+
+MetropolisJS has undergone a comprehensive three-phase refactoring to align with React best practices, improve type safety, and enhance developer experience.
+
+### Phase 1: Context-Based Configuration ✅
+
+**Status:** Complete (Backward Compatible)
+
+- Added `resolveEnvironmentConfig()` utility for environment-specific config resolution
+- Enhanced `MetropolisContext` with `config` and `flux` properties
+- Created `useMetropolisConfig()` and `useMetropolisFlux()` hooks
+- Configuration now available through React Context
+- Global `Config` class still works for backward compatibility
+
+**New Features:**
+- `useMetropolisConfig()` - Access config from React context
+- `useMetropolisFlux()` - Access flux instance from context
+- `resolveEnvironmentConfig()` - Resolve environment-specific configuration
+
+### Phase 2: Selective Action Creation & Specialized Hooks ✅
+
+**Status:** Complete (Backward Compatible)
+
+- Added selective action creation: `useMetropolis(['user', 'post'])`
+- Created 12 specialized hooks for individual action types
+- Improved type safety by removing `as any` casts
+- Better performance through selective action creation
+
+**New Features:**
+- `useUserActions()` - User management actions only
+- `usePostActions()` - Post management actions only
+- `useMessageActions()` - Messaging actions only
+- `useEventActions()` - Event management actions only
+- `useImageActions()` - Image handling actions only
+- `useLocationActions()` - Location services actions only
+- `useReactionActions()` - Reaction actions only
+- `useTagActions()` - Tag management actions only
+- `useContentActions()` - Content management actions only
+- `usePersonaActions()` - Persona management actions only
+- `useTranslationActions()` - Translation actions only
+- `useWebsocketActions()` - WebSocket actions only
+- Selective creation: `useMetropolis(['user', 'post'])`
+
+**Performance Improvements:**
+- Only creates actions you need
+- Better tree-shaking opportunities
+- More efficient memoization
+
+### Phase 3: Remove Global Config Singleton ✅
+
+**Status:** Complete (Breaking Changes)
+
+- Removed global `Config.set()` from Metropolis component
+- Config now stored in flux state (`app.config`)
+- Created `getConfigFromFlux()` utility for non-React code
+- Deprecated `Config.get()` and `Config.set()` with warnings
+- `useMetropolisConfig()` now requires Metropolis context
+
+**Breaking Changes:**
+- `useMetropolisConfig()` throws error if used outside Metropolis component
+- `Config.get()` and `Config.set()` are deprecated (show warnings)
+- Configuration must be passed to `<Metropolis>` component
+
+**Migration Required:**
+- React components: Use `useMetropolisConfig()` instead of `Config.get()`
+- Non-React code: Use `getConfigFromFlux(flux)` instead of `Config.get()`
+- Ensure components are wrapped with `<Metropolis>` provider
+
+## Summary of Changes
+
+### New Hooks
+
+1. **Configuration Hooks:**
+   - `useMetropolisConfig()` - Get configuration from context
+   - `useMetropolisFlux()` - Get flux instance from context
+
+2. **Specialized Action Hooks:**
+   - `useUserActions()`
+   - `usePostActions()`
+   - `useMessageActions()`
+   - `useEventActions()`
+   - `useImageActions()`
+   - `useLocationActions()`
+   - `useReactionActions()`
+   - `useTagActions()`
+   - `useContentActions()`
+   - `usePersonaActions()`
+   - `useTranslationActions()`
+   - `useWebsocketActions()`
+
+### Enhanced Features
+
+- **Selective Action Creation:** `useMetropolis(['user', 'post'])`
+- **Context-Based Configuration:** No global state
+- **Type Safety:** Removed `as any` casts
+- **Better Performance:** Only create needed actions
+
+### Deprecated APIs
+
+- `Config.get()` - Use `useMetropolisConfig()` or `getConfigFromFlux(flux)`
+- `Config.set()` - Pass config to `<Metropolis>` component
+
+### New Utilities
+
+- `getConfigFromFlux(flux)` - Get config from flux state (for non-React code)
+- `resolveEnvironmentConfig(config)` - Resolve environment-specific config
+
+## Migration Guide
+
+See the [README.md](./README.md) for detailed migration examples and usage patterns.

package/GRAPHQL_VALIDATION_RESULTS.md

@@ -0,0 +1,158 @@
+# GraphQL SignIn Validation - Complete Analysis
+
+## Summary
+
+✅ **Client Code Status:** CORRECT
+✅ **Unit Tests Created:** 10 tests, all PASSING
+🔴 **Server Issue:** GraphQL schema missing `users` field on `Mutation` type
+
+## Test Results
+
+When running `npm test src/utils/api.signin.test.ts`, all tests pass:
+
+```
+PASS @nlabs/lex src/utils/api.signin.test.ts
+
+SignIn GraphQL Mutation Generation
+  createMutation with signIn
+    ✓ should generate correct mutation shape with users wrapper (18 ms)
+    ✓ should generate mutation with correct GraphQL syntax structure
+    ✓ should handle signIn with only required parameters (1 ms)
+    ✓ should create complete signin mutation payload
+  refreshSession mutation
+    ✓ should generate correct refreshSession mutation (1 ms)
+  signUp mutation
+    ✓ should generate correct signUp mutation with users wrapper (1 ms)
+  API Response Handler
+    ✓ should correctly extract signIn session from users wrapper
+    ✓ should handle missing users wrapper gracefully
+    ✓ should handle nested data extraction for other mutations
+  Expected Server GraphQL Schema
+    ✓ should document the expected Mutation type structure for server implementation
+
+Test Suites: 1 passed, 1 total
+Tests:       10 passed, 10 total
+```
+
+## Test Coverage
+
+### 1. Mutation Generation Tests ✅
+
+Tests verify that the `createMutation()` function generates the correct GraphQL structure:
+
+**Generated SignIn Mutation:**
+```graphql
+mutation UsersSignIn($expires: Int, $password: String!, $username: String!) {
+  users {
+    signIn(expires: $expires, password: $password, username: $username) {
+      expires
+      issued
+      token
+      userId
+      username
+    }
+  }
+}
+```
+
+**Generated RefreshSession Mutation:**
+```graphql
+mutation UsersRefreshSession($expires: Int, $token: String!) {
+  users {
+    refreshSession(expires: $expires, token: $token) {
+      expires
+      issued
+      token
+    }
+  }
+}
+```
+
+**Generated SignUp Mutation:**
+```graphql
+mutation UsersSignUp($user: UserInput!) {
+  users {
+    signUp(user: $user) {
+      userId
+      username
+    }
+  }
+}
+```
+
+### 2. Response Handler Tests ✅
+
+Tests verify correct data extraction from nested response structure:
+
+- ✅ `data.users.signIn` is correctly extracted
+- ✅ Missing wrapper is handled gracefully
+- ✅ Other mutations follow the same pattern: `data.{collection}.{method}`
+
+### 3. Schema Documentation ✅
+
+Tests document the expected server GraphQL schema structure needed to support these mutations.
+
+## What Needs to be Fixed on Server
+
+The server at `/Users/nitrog7/Development/vault` must have this schema structure:
+
+```graphql
+type Mutation {
+  users: UsersMutation!
+}
+
+type UsersMutation {
+  signIn(username: String!, password: String!, expires: Int): Session
+  signUp(user: UserInput!): User
+  update(user: UserUpdateInput!): User
+  updateProfile(profile: ProfileUpdateInput!): Profile
+  refreshSession(token: String!, expires: Int): Session
+  confirmCode(code: Int!, type: String!, value: String!): Boolean
+  remove(userId: String!): User
+  session(user: UserInput!): User
+  itemById(userId: String!): User
+}
+
+type Session {
+  token: String!
+  expires: Int
+  issued: Int
+  userId: String
+  username: String
+}
+```
+
+## Client-Side Architecture
+
+The metropolisjs library uses a **collection-type wrapper pattern** for all GraphQL mutations:
+
+| Collection | Mutations | Response |
+|-----------|-----------|----------|
+| `users` | signIn, signUp, update, refreshSession, ... | `data.users.{method}` |
+| `posts` | add, delete, update, ... | `data.posts.{method}` |
+| `contents` | add, delete, update, ... | `data.contents.{method}` |
+| `reactions` | addReaction, deleteReaction | `data.reactions.{method}` |
+
+This is intentional and consistent across the codebase.
+
+## Files
+
+- **Test File:** [src/utils/api.signin.test.ts](../src/utils/api.signin.test.ts)
+- **API Implementation:** [src/utils/api.ts](../src/utils/api.ts)
+- **User Actions:** [src/actions/userActions/userActions.ts](../src/actions/userActions/userActions.ts)
+
+## Next Steps
+
+1. ✅ Client-side validation complete
+2. ⏳ Update server GraphQL schema at `/Users/nitrog7/Development/vault`
+3. ⏳ Verify signin mutation works with updated schema
+4. ⏳ Run full integration tests
+
+## How to Run Tests
+
+```bash
+cd /Users/nitrog7/Development/metropolisjs
+npm test -- src/utils/api.signin.test.ts
+```
+
+All tests pass with the Lex test runner configured in `lex.config.mjs`.