@nlabs/metropolisjs 0.1.2 → 0.3.0

package/SIGNIN_GRAPHQL_VALIDATION.md

@@ -0,0 +1,125 @@
+# SignIn GraphQL Error Analysis and Fix
+
+## Problem
+The client is throwing a GraphQL validation error:
+```
+Cannot query field "users" on type "Mutation"
+```
+
+With the mutation payload:
+```
+mutation UsersSignIn($expires: Int, $password: String!, $username: String!) {
+  users {
+    signIn(expires: $expires, password: $password, username: $username) {
+      expires
+      issued
+      token
+      userId
+      username
+    }
+  }
+}
+```
+
+## Root Cause
+The client code is correctly generating the mutation with a `users` wrapper as the parent collection type. However, the **server GraphQL schema** does not define a `users` field on the `Mutation` type.
+
+## Client Code Status ✅
+All client code is **correct and working as designed**:
+- [src/utils/api.ts](src/utils/api.ts) - GraphQL query/mutation builder generates proper mutation structure
+- [src/actions/userActions/userActions.ts](src/actions/userActions/userActions.ts) - SignIn action correctly handles nested response
+- All response handlers expect `data.users.{method}` structure
+
+The client follows a consistent collection-type wrapper pattern:
+- User mutations: `users { signIn | signUp | update | ... }`
+- Post mutations: `posts { add | delete | update | ... }`
+- Content mutations: `contents { add | delete | update | ... }`
+- Reaction mutations: `reactions { addReaction | deleteReaction | ... }`
+
+## Unit Tests ✅
+Comprehensive unit tests have been created in [src/utils/api.signin.test.ts](src/utils/api.signin.test.ts) to validate:
+
+1. **Mutation Generation Tests** (4 tests)
+   - ✅ Correct mutation shape with users wrapper
+   - ✅ Proper GraphQL syntax structure
+   - ✅ Handling required vs optional parameters
+   - ✅ Complete signin payload generation
+
+2. **RefreshSession & SignUp Tests** (2 tests)
+   - ✅ RefreshSession mutation structure
+   - ✅ SignUp mutation structure
+
+3. **Response Handler Tests** (3 tests)
+   - ✅ Extract signIn session from users wrapper
+   - ✅ Handle missing users wrapper gracefully
+   - ✅ Handle nested data extraction for other mutations
+
+4. **Schema Documentation** (1 test)
+   - ✅ Documents expected Mutation type structure
+
+**Test Results:** All 10 tests pass ✓
+
+## Server Schema Fix Required 🔧
+
+The server GraphQL schema at `/Users/nitrog7/Development/vault` must be updated to include:
+
+```graphql
+type Mutation {
+  users: UsersMutation!
+  posts: PostsMutation!
+  contents: ContentsMutation!
+  reactions: ReactionsMutation!
+  # ... other collection types
+}
+
+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
+}
+
+# Similar structures for PostsMutation, ContentsMutation, ReactionsMutation, etc.
+```
+
+## Expected Client Response Structure
+After the server schema is updated, the GraphQL response will have the structure:
+
+```json
+{
+  "data": {
+    "users": {
+      "signIn": {
+        "token": "auth-token-xxx",
+        "expires": 1609459200,
+        "issued": 1609372800,
+        "userId": "user-123",
+        "username": "testuser"
+      }
+    }
+  }
+}
+```
+
+## Verification Steps
+1. ✅ Client code verified to generate correct mutation structure
+2. ✅ Unit tests pass, validating GraphQL payload generation
+3. 🔄 **PENDING:** Update server schema at `/Users/nitrog7/Development/vault` to support `users` field on `Mutation` type
+4. 🔄 **PENDING:** Test signin endpoint after server schema update
+
+## Files Modified
+- **Created:** [src/utils/api.signin.test.ts](src/utils/api.signin.test.ts) - Comprehensive mutation generation tests
+- **Not Modified:** Client mutation generation code is correct as-is

package/VAULT_GRAPHQL_API_FINDINGS.md

@@ -0,0 +1,312 @@
+# Vault GraphQL API - Schema and Mutations Analysis
+
+## Overview
+This document contains the actual GraphQL schema definitions from the Vault server located at `/Users/nitrog7/Development/vault/api/src/graphql/`.
+
+---
+
+## 1. MUTATION TYPE DEFINITIONS
+
+The actual mutations available in the Vault GraphQL API are defined across two key places:
+
+### Root Mutations (rootSchema.ts)
+```graphql
+type Mutation {
+  # Projects
+  createProject(input: ProjectInput!): Project!
+  updateProjectConfig(id: ID!, config: ProjectConfigInput!): Project!
+
+  # Chapters
+  createChapter(projectId: ID!, input: ChapterInput!): Chapter!
+
+  # Files & Git
+  writeFile(projectId: ID!, input: FileWriteInput!): Boolean!
+
+  # Proposals & AI
+  proposeEdit(projectId: ID!, input: EditProposalInput!): Proposal!
+  acceptProposal(projectId: ID!, proposalId: ID!): Boolean!
+  rejectProposal(projectId: ID!, proposalId: ID!): Boolean!
+
+  # Context
+  createContextProfile(projectId: ID!, input: ContextProfileInput!): ContextProfile!
+  updateContextProfile(projectId: ID!, profileId: ID!, input: ContextProfileInput!): ContextProfile!
+  deleteContextProfile(projectId: ID!, profileId: ID!): Boolean!
+  buildContext(projectId: ID!, input: ContextBuildInput!): ContextBuildResult!
+
+  # Midjourney
+  compilePrompts(projectId: ID!, input: MidjourneyCompileInput!): MidjourneyCompileResult!
+
+  # Auth (User Operations)
+  signUp(input: SignUpInput!): AuthResponse!
+  signIn(user: User!, password: String!, expires: Int): AuthToken!
+  signOut: Boolean!
+  forgotPassword(username: String!): AuthResponse!
+  resetPassword(input: ResetPasswordInput!): AuthResponse!
+}
+```
+
+---
+
+## 2. USER INPUT TYPES
+
+### **UserInput Type** (DEFINED)
+**Location:** `schema.ts` (old schema, not currently used)
+
+```graphql
+input UserInput {
+  username: String!
+  email: String!
+  name: String!
+  password: String!
+}
+```
+
+**Status:** This type is defined but **NOT used** in any current mutations. It appears to be a legacy definition.
+
+---
+
+### **SignUpInput Type** (ACTUAL - authSchema.ts)
+```graphql
+input SignUpInput {
+  email: String!
+  password: String!
+  name: String
+}
+```
+
+**Used in mutation:**
+```graphql
+signUp(input: SignUpInput!): AuthResponse!
+```
+
+**Implementation Details (authResolvers.ts):**
+- Email is required
+- Password is required
+- Name is optional
+- Username is automatically set to email
+- Calls `addUser()` from `@nlabs/reaktor`
+
+---
+
+### **SignInInput Type** (ACTUAL - authSchema.ts)
+```graphql
+input SignInInput {
+  email: String!
+  password: String!
+}
+```
+
+**Current Mutation Signature (Different):**
+```graphql
+signIn(user: User!, password: String!, expires: Int): AuthToken!
+```
+
+⚠️ **NOTE:** The mutation signature doesn't match the `SignInInput` type. It directly takes:
+- `user: User!` (not `email`, but a full User object)
+- `password: String!`
+- `expires: Int` (optional, in seconds)
+
+---
+
+### **ResetPasswordInput Type** (ACTUAL - authSchema.ts)
+```graphql
+input ResetPasswordInput {
+  username: String!
+  code: Int!
+  password: String!
+  type: String!
+}
+```
+
+**Used in mutation:**
+```graphql
+resetPassword(input: ResetPasswordInput!): AuthResponse!
+```
+
+---
+
+## 3. USER MUTATIONS SUMMARY
+
+### Available User Mutations:
+
+| Mutation | Input Type | Purpose |
+|----------|-----------|---------|
+| `signUp` | `SignUpInput` | Register a new user account |
+| `signIn` | Direct params (not input type) | Authenticate user and get session token |
+| `signOut` | None | Logout/terminate session |
+| `forgotPassword` | Direct param: `username: String!` | Request password reset code |
+| `resetPassword` | `ResetPasswordInput` | Reset password with verification code |
+
+### User Query:
+```graphql
+type Query {
+  me: User  # Get current authenticated user
+}
+```
+
+---
+
+## 4. USER TYPE DEFINITION
+
+The User type is defined in the auth schema:
+
+```graphql
+type User {
+  _key: ID!
+  email: String!
+  username: String
+  name: String
+  createdAt: String!
+  updatedAt: String!
+}
+```
+
+**Note:** Password is never returned in responses.
+
+---
+
+## 5. AUTHENTICATION RESPONSE TYPES
+
+### AuthResponse (for signUp, forgotPassword, resetPassword)
+```graphql
+type AuthResponse {
+  success: Boolean!
+  message: String
+  token: String
+  expires: Float
+  userId: String
+  username: String
+}
+```
+
+### AuthToken (for signIn)
+```graphql
+type AuthToken {
+  token: String!
+  expires: Float!
+  userId: String!
+  username: String!
+}
+```
+
+---
+
+## 6. ALL INPUT TYPES IN THE VAULT API
+
+### Project-related:
+- `ProjectInput` - Create/update project
+- `ProjectConfigInput` - Project configuration
+
+### Chapter-related:
+- `ChapterInput` - Create chapter
+
+### File-related:
+- `FileWriteInput` - Write/create file
+
+### Context-related:
+- `ContextProfileInput` - Create/update context profile
+- `ContextBuildInput` - Build context
+
+### Proposal-related:
+- `EditProposalInput` - Propose edit
+
+### Midjourney-related:
+- `MidjourneyCompileInput` - Compile prompts
+
+### Auth-related:
+- **`SignUpInput`** - User registration
+- **`SignInInput`** - (defined but not used in mutation)
+- **`ResetPasswordInput`** - Password reset
+
+### Legacy (not used):
+- `UserInput` - Old definition, not used in any current mutations
+
+---
+
+## 7. IMPLEMENTATION NOTES
+
+### Sign Up Flow (authResolvers.ts):
+```typescript
+signUp: async (_: any, { input }: any) => {
+  // Input: { email, password, name }
+  // Sets username = email
+  // Calls @nlabs/reaktor addUser()
+  // Returns AuthResponse (without token initially)
+}
+```
+
+### Sign In Flow (authResolvers.ts):
+```typescript
+signIn: async (_: any, { email, password, expires }: any) => {
+  // Calls @nlabs/reaktor signIn()
+  // Returns AuthToken with token, userId, username, expires
+  // Default expires: 15 minutes (in seconds)
+}
+```
+
+### Sign Out Flow:
+```typescript
+signOut: async (_: any, __: any, context: any) => {
+  // Requires authenticated context
+  // Calls @nlabs/reaktor signOut()
+  // Returns Boolean
+}
+```
+
+### Password Reset Flow:
+```typescript
+forgotPassword: async (_: any, { username }: any) => {
+  // Sends reset code via email using @nlabs/reaktor
+  // Returns success message (doesn't reveal if user exists)
+}
+
+resetPassword: async (_: any, { input }: any) => {
+  // Validates code
+  // Updates password
+  // Returns success response
+}
+```
+
+---
+
+## 8. KEY FINDINGS
+
+✅ **YES - UserInput Type IS Defined**
+- Location: `schema.ts` (line ~200)
+- Fields: `username`, `email`, `name`, `password`
+- Status: **Not used in any current mutations**
+
+✅ **Actual User Mutation Input Types:**
+- `SignUpInput` - email, password, name
+- `SignInInput` - email, password (defined but not used in mutation)
+- `ResetPasswordInput` - username, code, password, type
+
+✅ **User Mutations Available:**
+1. `signUp(input: SignUpInput!): AuthResponse!`
+2. `signIn(user: User!, password: String!, expires: Int): AuthToken!`
+3. `signOut: Boolean!`
+4. `forgotPassword(username: String!): AuthResponse!`
+5. `resetPassword(input: ResetPasswordInput!): AuthResponse!`
+
+⚠️ **Discrepancy:**
+- `SignInInput` type is defined but the actual `signIn` mutation doesn't use it
+- The mutation takes `user: User!` object directly instead of email/password inputs
+
+---
+
+## 9. SCHEMA FILE LOCATIONS
+
+All schema definitions are in: `/Users/nitrog7/Development/vault/api/src/graphql/schema/`
+
+- `index.ts` - Main composite schema
+- `rootSchema.ts` - Root Query and Mutation definitions
+- `authSchema.ts` - Auth types and inputs
+- `projectSchema.ts` - Project types and inputs
+- `chapterSchema.ts` - Chapter types and inputs
+- `fileSchema.ts` - File types and inputs
+- `contextSchema.ts` - Context types and inputs
+- `diffSchema.ts` - Diff/Proposal types and inputs
+- `midjourneySchema.ts` - Midjourney types and inputs
+
+Resolvers are in: `/Users/nitrog7/Development/vault/api/src/graphql/resolvers/authResolvers.ts`
+

package/docs/ACTIONS.md

@@ -0,0 +1,63 @@
+# MetropolisJS Actions Reference
+
+This reference documents every action family exposed by MetropolisJS, how to access it, and where to find the full TypeScript interface.
+
+## Access Patterns
+
+Use specialized hooks in React components:
+
+```tsx
+import {useUserActions, usePostActions, useMessageActions} from '@nlabs/metropolisjs';
+
+const userActions = useUserActions();
+const postActions = usePostActions();
+const messageActions = useMessageActions();
+```
+
+Or create actions directly with a Flux instance:
+
+```ts
+import {createUserActions, createPostActions} from '@nlabs/metropolisjs';
+
+const userActions = createUserActions(flux);
+const postActions = createPostActions(flux);
+```
+
+## Action Families
+
+Each row links to:
+- source implementation (`src/actions/...`)
+- 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 |
+| --- | --- | --- | --- | --- |
+| 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) |
+
+## Full Exports
+
+All action creators are re-exported from:
+
+- [src/actions/index.ts](../src/actions/index.ts)
+
+All specialized hooks are exposed from:
+
+- [src/utils/useMetropolis.ts](../src/utils/useMetropolis.ts)