refactor(convex): remove unnecessary `as` type assertions

[larryro]

Problem Statement

The Convex directory contains approximately 900+ as type assertions that bypass TypeScript's type system. This violates the project guidelines: "DO NOT use type casting. Avoid any, and unknown whenever possible."

Many of these assertions are unnecessary and can be replaced with proper type annotations following Convex best practices.

Current State

Type assertions are used in several problematic patterns:

1. Better Auth Integration - Returns any types, causing cascading assertions
2. Schema fields via as any - Accessing existing schema fields unnecessarily
3. External API responses - Untyped JSON responses (RAG, IMAP)
4. Metadata field access - Repeated casts for same structure
5. Handler return types - Missing explicit type annotations

Proposed Solution

Replace type assertions with proper TypeScript typing:

1. Create typed interfaces for Better Auth adapter responses
2. Create typed interfaces for external API responses (RAG, IMAP, etc.)
3. Create document metadata type definitions
4. Add explicit return type annotations to Convex handlers
5. Use direct property access instead of as any casts for schema-defined fields

Affected Components

• convex/member.ts - Better Auth member operations
• convex/documents.ts - Document management
• convex/model/documents/transform_to_document_item.ts - Document transformation
• convex/workflow/actions/rag/helpers/upload_file_direct.ts - RAG upload
• convex/workflow/actions/rag/helpers/get_document_info.ts - RAG info
• convex/workflow/actions/imap/helpers/get_imap_credentials.ts - IMAP credentials
• convex/model/conversations/transform_conversation.ts - Conversation transformation
• convex/workflow_assistant_agent.ts - Workflow agent
• ~40-50 other Convex files

Acceptance Criteria

• All as any casts removed (except where strictly necessary)
• Better Auth response types defined and used
• RAG API response types defined and used
• Document metadata types defined and used
• All Convex handlers have explicit return type annotations
• TypeScript compiles without errors (npx convex dev --once)
• Build succeeds (npm run build)

---

🤖 Generated with Claude Code

[larryro]

Implementation Plan

Phase 1: Create Type Definitions

1.1 Better Auth Types (convex/model/members/types.ts)

export interface BetterAuthUser {
  _id: string;
  email?: string;
  name?: string;
  image?: string;
  createdAt: number;
  updatedAt: number;
}

export interface BetterAuthMember {
  _id: string;
  organizationId: string;
  userId: string;
  role?: string;
  createdAt: number;
}

1.2 Document Metadata Types (convex/model/documents/types.ts)

export interface DocumentMetadata {
  name?: string;
  type?: 'file' | 'folder';
  size?: number;
  mimeType?: string;
  extension?: string;
  storagePath?: string;
  sourceProvider?: string;
  sourceMode?: string;
  lastModified?: number;
  syncConfigId?: string;
  isDirectlySelected?: boolean;
}

1.3 RAG API Response Types (convex/workflow/actions/rag/helpers/types.ts)

export interface RagUploadResponse {
  document_id?: string;
  id?: string;
  queued?: boolean;
  job_id?: string;
  success?: boolean;
  chunks_created?: number;
}

export interface RagDocumentInfo {
  id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  chunks_count?: number;
  error?: string;
}

Phase 2: Fix High Priority Files

1. member.ts - Replace (m: any) with typed BetterAuthMember interface
2. transform_to_document_item.ts - Remove as any, use direct property access for ragInfo
3. upload_file_direct.ts - Use RagUploadResponse interface for API response
4. get_document_info.ts - Use RagDocumentInfo interface
5. get_imap_credentials.ts - Type IMAP credential response

Phase 3: Fix Medium Priority Files

Work through remaining files systematically:

• Add explicit handler return types
• Replace as casts with proper typing
• Create domain-specific type definitions as needed

Files to Modify (Grouped by Domain)

Group	Files	Assertions
Member Management	member.ts	15
Documents	documents.ts, transform_to_document_item.ts	25
Workflows	wf_definitions.ts, workflow_assistant_agent.ts	25
RAG	upload_file_direct.ts, get_document_info.ts	23
Email/IMAP	get_imap_credentials.ts, email_provider_action.ts	14+
Conversations	transform_conversation.ts, streaming.ts	24
External Actions	product_action.ts, onedrive_action.ts	24
Agent Tools	pptx_tool.ts, generate_agent_response.ts	TBD
Auth	auth.ts	8

Phase 4: Validation

1. Run npx convex dev --once after each group (Convex type generation + validation)
2. Run npm run typecheck for full TypeScript validation
3. Run npm run build for production build verification

Potential Risks

Risk	Mitigation
Type definitions don't match runtime data	Review actual API responses before defining types
Breaking changes to interfaces	Keep changes internal, don't modify public API contracts
Missing edge cases	Add optional fields with ? to handle variations

Testing Strategy

• Unit Testing: Type checking validates at compile time
• Manual Testing:
  • Member CRUD operations
  • Document upload and RAG indexing
  • Email provider operations
  • Workflow execution

---

🤖 Generated with Claude Code