@nextsparkjs/theme-crm 0.1.0-beta.1

package/entities/notes/notes.service.ts

@@ -0,0 +1,320 @@
+/**
+ * Notes Service
+ *
+ * Provides data access methods for notes.
+ * Notes is a private entity - users only see notes in their team.
+ *
+ * All methods require authentication (use RLS with userId filter).
+ *
+ * @module NotesService
+ */
+
+import { queryOneWithRLS, queryWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db'
+
+// Note interface
+export interface Note {
+  id: string
+  content: string
+  relatedTo?: string
+  relatedId?: string
+  createdAt: string
+  updatedAt: string
+}
+
+// List options
+export interface NoteListOptions {
+  limit?: number
+  offset?: number
+  relatedTo?: string
+  relatedId?: string
+  orderBy?: 'createdAt' | 'updatedAt'
+  orderDir?: 'asc' | 'desc'
+  teamId?: string
+}
+
+// List result
+export interface NoteListResult {
+  notes: Note[]
+  total: number
+}
+
+// Create data
+export interface NoteCreateData {
+  content: string
+  relatedTo?: string
+  relatedId?: string
+  teamId: string
+}
+
+// Update data
+export interface NoteUpdateData {
+  content?: string
+  relatedTo?: string
+  relatedId?: string
+}
+
+// Database row type
+interface DbNote {
+  id: string
+  content: string
+  relatedTo: string | null
+  relatedId: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export class NotesService {
+  // ============================================
+  // READ METHODS
+  // ============================================
+
+  /**
+   * Get a note by ID
+   */
+  static async getById(id: string, userId: string): Promise<Note | null> {
+    try {
+      if (!id?.trim()) throw new Error('Note ID is required')
+      if (!userId?.trim()) throw new Error('User ID is required')
+
+      const note = await queryOneWithRLS<DbNote>(
+        `SELECT id, content, "relatedTo", "relatedId", "createdAt", "updatedAt"
+         FROM notes WHERE id = $1`,
+        [id],
+        userId
+      )
+
+      if (!note) return null
+
+      return {
+        id: note.id,
+        content: note.content,
+        relatedTo: note.relatedTo ?? undefined,
+        relatedId: note.relatedId ?? undefined,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+      }
+    } catch (error) {
+      console.error('NotesService.getById error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to fetch note')
+    }
+  }
+
+  /**
+   * List notes with pagination and filtering
+   */
+  static async list(userId: string, options: NoteListOptions = {}): Promise<NoteListResult> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+
+      const {
+        limit = 10,
+        offset = 0,
+        relatedTo,
+        relatedId,
+        orderBy = 'createdAt',
+        orderDir = 'desc',
+        teamId,
+      } = options
+
+      // Build WHERE clause
+      const conditions: string[] = []
+      const params: unknown[] = []
+      let paramIndex = 1
+
+      if (relatedTo) {
+        conditions.push(`"relatedTo" = $${paramIndex++}`)
+        params.push(relatedTo)
+      }
+
+      if (relatedId) {
+        conditions.push(`"relatedId" = $${paramIndex++}`)
+        params.push(relatedId)
+      }
+
+      if (teamId) {
+        conditions.push(`"teamId" = $${paramIndex++}`)
+        params.push(teamId)
+      }
+
+      const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+
+      // Validate orderBy
+      const validOrderBy = ['createdAt', 'updatedAt'].includes(orderBy) ? orderBy : 'createdAt'
+      const validOrderDir = orderDir === 'asc' ? 'ASC' : 'DESC'
+      const orderColumnMap: Record<string, string> = {
+        createdAt: '"createdAt"',
+        updatedAt: '"updatedAt"',
+      }
+      const orderColumn = orderColumnMap[validOrderBy] || '"createdAt"'
+
+      // Get total count
+      const countResult = await queryWithRLS<{ count: string }>(
+        `SELECT COUNT(*)::text as count FROM notes ${whereClause}`,
+        params,
+        userId
+      )
+      const total = parseInt(countResult[0]?.count || '0', 10)
+
+      // Get notes
+      params.push(limit, offset)
+      const notes = await queryWithRLS<DbNote>(
+        `SELECT id, content, "relatedTo", "relatedId", "createdAt", "updatedAt"
+         FROM notes ${whereClause}
+         ORDER BY ${orderColumn} ${validOrderDir}
+         LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`,
+        params,
+        userId
+      )
+
+      return {
+        notes: notes.map((note) => ({
+          id: note.id,
+          content: note.content,
+          relatedTo: note.relatedTo ?? undefined,
+          relatedId: note.relatedId ?? undefined,
+          createdAt: note.createdAt,
+          updatedAt: note.updatedAt,
+        })),
+        total,
+      }
+    } catch (error) {
+      console.error('NotesService.list error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to list notes')
+    }
+  }
+
+  /**
+   * Get notes related to an entity
+   */
+  static async getByRelatedEntity(userId: string, relatedTo: string, relatedId: string, limit = 50): Promise<Note[]> {
+    const { notes } = await this.list(userId, {
+      relatedTo,
+      relatedId,
+      limit,
+      orderBy: 'createdAt',
+      orderDir: 'desc',
+    })
+    return notes
+  }
+
+  // ============================================
+  // WRITE METHODS
+  // ============================================
+
+  /**
+   * Create a new note
+   */
+  static async create(userId: string, data: NoteCreateData): Promise<Note> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!data.content?.trim()) throw new Error('Content is required')
+      if (!data.teamId?.trim()) throw new Error('Team ID is required')
+
+      const id = crypto.randomUUID()
+      const now = new Date().toISOString()
+
+      const result = await mutateWithRLS<DbNote>(
+        `INSERT INTO notes (id, "userId", "teamId", content, "relatedTo", "relatedId", "createdAt", "updatedAt")
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+         RETURNING id, content, "relatedTo", "relatedId", "createdAt", "updatedAt"`,
+        [
+          id,
+          userId,
+          data.teamId,
+          data.content,
+          data.relatedTo || null,
+          data.relatedId || null,
+          now,
+          now,
+        ],
+        userId
+      )
+
+      if (!result.rows[0]) throw new Error('Failed to create note')
+
+      const note = result.rows[0]
+      return {
+        id: note.id,
+        content: note.content,
+        relatedTo: note.relatedTo ?? undefined,
+        relatedId: note.relatedId ?? undefined,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+      }
+    } catch (error) {
+      console.error('NotesService.create error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to create note')
+    }
+  }
+
+  /**
+   * Update an existing note
+   */
+  static async update(userId: string, id: string, data: NoteUpdateData): Promise<Note> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!id?.trim()) throw new Error('Note ID is required')
+
+      const updates: string[] = []
+      const values: unknown[] = []
+      let paramIndex = 1
+
+      if (data.content !== undefined) {
+        updates.push(`content = $${paramIndex++}`)
+        values.push(data.content)
+      }
+      if (data.relatedTo !== undefined) {
+        updates.push(`"relatedTo" = $${paramIndex++}`)
+        values.push(data.relatedTo || null)
+      }
+      if (data.relatedId !== undefined) {
+        updates.push(`"relatedId" = $${paramIndex++}`)
+        values.push(data.relatedId || null)
+      }
+
+      if (updates.length === 0) throw new Error('No fields to update')
+
+      updates.push(`"updatedAt" = $${paramIndex++}`)
+      values.push(new Date().toISOString())
+      values.push(id)
+
+      const result = await mutateWithRLS<DbNote>(
+        `UPDATE notes SET ${updates.join(', ')} WHERE id = $${paramIndex}
+         RETURNING id, content, "relatedTo", "relatedId", "createdAt", "updatedAt"`,
+        values,
+        userId
+      )
+
+      if (!result.rows[0]) throw new Error('Note not found or update failed')
+
+      const note = result.rows[0]
+      return {
+        id: note.id,
+        content: note.content,
+        relatedTo: note.relatedTo ?? undefined,
+        relatedId: note.relatedId ?? undefined,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+      }
+    } catch (error) {
+      console.error('NotesService.update error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to update note')
+    }
+  }
+
+  /**
+   * Delete a note
+   */
+  static async delete(userId: string, id: string): Promise<boolean> {
+    try {
+      if (!userId?.trim()) throw new Error('User ID is required')
+      if (!id?.trim()) throw new Error('Note ID is required')
+
+      const result = await mutateWithRLS(`DELETE FROM notes WHERE id = $1`, [id], userId)
+      return result.rowCount > 0
+    } catch (error) {
+      console.error('NotesService.delete error:', error)
+      throw new Error(error instanceof Error ? error.message : 'Failed to delete note')
+    }
+  }
+}

package/entities/notes/notes.types.ts

@@ -0,0 +1,102 @@
+/**
+ * Note Service Types
+ *
+ * Type definitions for the NoteService.
+ * Defines types for note management with flexible entity relationships,
+ * privacy controls, and attachment support.
+ *
+ * @module NoteTypes
+ */
+
+// Type literals for select fields
+export type NoteType =
+  | 'general'
+  | 'call'
+  | 'meeting'
+  | 'email'
+  | 'followup'
+  | 'feedback'
+  | 'reminder'
+
+export type NoteEntityType = 'lead' | 'contact' | 'company' | 'opportunity' | 'campaign'
+
+// Attachment interface
+export interface NoteAttachment {
+  name: string
+  url: string
+  size?: number
+  type?: string
+}
+
+// Main entity interface
+export interface Note {
+  id: string
+  teamId: string
+  title?: string | null
+  content: string
+  type?: NoteType | null
+  isPinned?: boolean | null
+  isPrivate?: boolean | null
+  entityType?: NoteEntityType | null
+  entityId?: string | null
+  contactId?: string | null
+  companyId?: string | null
+  opportunityId?: string | null
+  attachments?: NoteAttachment[] | null
+  createdAt: string
+  updatedAt: string
+}
+
+// List options
+export interface NoteListOptions {
+  limit?: number
+  offset?: number
+  teamId?: string
+  type?: NoteType
+  isPinned?: boolean
+  isPrivate?: boolean
+  entityType?: NoteEntityType
+  entityId?: string
+  contactId?: string
+  companyId?: string
+  opportunityId?: string
+  orderBy?: 'title' | 'type' | 'isPinned' | 'isPrivate' | 'createdAt' | 'updatedAt'
+  orderDir?: 'asc' | 'desc'
+}
+
+// List result
+export interface NoteListResult {
+  notes: Note[]
+  total: number
+}
+
+// Create data (required fields + teamId + optional fields)
+export interface NoteCreateData {
+  content: string
+  teamId: string
+  title?: string
+  type?: NoteType
+  isPinned?: boolean
+  isPrivate?: boolean
+  entityType?: NoteEntityType
+  entityId?: string
+  contactId?: string
+  companyId?: string
+  opportunityId?: string
+  attachments?: NoteAttachment[]
+}
+
+// Update data (all fields optional)
+export interface NoteUpdateData {
+  title?: string | null
+  content?: string
+  type?: NoteType | null
+  isPinned?: boolean | null
+  isPrivate?: boolean | null
+  entityType?: NoteEntityType | null
+  entityId?: string | null
+  contactId?: string | null
+  companyId?: string | null
+  opportunityId?: string | null
+  attachments?: NoteAttachment[] | null
+}

package/entities/opportunities/messages/en.json

@@ -0,0 +1,107 @@
+{
+  "entity": {
+    "name": "Opportunity",
+    "plural": "Opportunities",
+    "description": "Manage sales opportunities"
+  },
+  "fields": {
+    "name": {
+      "label": "Opportunity Name",
+      "description": "Opportunity name or title",
+      "placeholder": "Enter opportunity name..."
+    },
+    "companyId": {
+      "label": "Company",
+      "description": "Company this opportunity belongs to",
+      "placeholder": "Select company..."
+    },
+    "contactId": {
+      "label": "Primary Contact",
+      "description": "Primary contact for this opportunity",
+      "placeholder": "Select contact..."
+    },
+    "pipelineId": {
+      "label": "Pipeline",
+      "description": "Pipeline this opportunity is in",
+      "placeholder": "Select pipeline..."
+    },
+    "stageId": {
+      "label": "Stage",
+      "description": "Current stage in pipeline",
+      "placeholder": "Stage ID from pipeline"
+    },
+    "amount": {
+      "label": "Deal Amount",
+      "description": "Deal amount value",
+      "placeholder": "0.00"
+    },
+    "currency": {
+      "label": "Currency",
+      "description": "Currency code for amount",
+      "placeholder": "Select currency..."
+    },
+    "probability": {
+      "label": "Win Probability (%)",
+      "description": "Win probability percentage",
+      "placeholder": "0"
+    },
+    "expectedRevenue": {
+      "label": "Expected Revenue",
+      "description": "Calculated expected revenue"
+    },
+    "closeDate": {
+      "label": "Expected Close Date",
+      "description": "Expected or actual close date",
+      "placeholder": "Select date..."
+    },
+    "type": {
+      "label": "Opportunity Type",
+      "description": "Type of opportunity",
+      "placeholder": "Select type..."
+    },
+    "source": {
+      "label": "Source",
+      "description": "Source of the opportunity",
+      "placeholder": "Select source..."
+    },
+    "status": {
+      "label": "Status",
+      "description": "Current opportunity status",
+      "placeholder": "Select status..."
+    },
+    "assignedTo": {
+      "label": "Assigned To",
+      "description": "Sales rep assigned to opportunity",
+      "placeholder": "Select user..."
+    }
+  },
+  "options": {
+    "type": {
+      "new_business": "New Business",
+      "existing_business": "Existing Business",
+      "renewal": "Renewal",
+      "upgrade": "Upgrade",
+      "downgrade": "Downgrade"
+    },
+    "status": {
+      "open": "Open",
+      "won": "Won",
+      "lost": "Lost",
+      "abandoned": "Abandoned"
+    }
+  },
+  "actions": {
+    "create": "Create Opportunity",
+    "edit": "Edit Opportunity",
+    "delete": "Delete Opportunity",
+    "view": "View Opportunity",
+    "list": "List Opportunities"
+  },
+  "messages": {
+    "created": "Opportunity created successfully",
+    "updated": "Opportunity updated successfully",
+    "deleted": "Opportunity deleted successfully",
+    "notFound": "Opportunity not found",
+    "error": "An error occurred while processing the opportunity"
+  }
+}

package/entities/opportunities/messages/es.json

@@ -0,0 +1,107 @@
+{
+  "entity": {
+    "name": "Oportunidad",
+    "plural": "Oportunidades",
+    "description": "Gestiona oportunidades de venta"
+  },
+  "fields": {
+    "name": {
+      "label": "Nombre",
+      "description": "Nombre de la oportunidad",
+      "placeholder": "Ingrese nombre..."
+    },
+    "companyId": {
+      "label": "Empresa",
+      "description": "Empresa asociada",
+      "placeholder": "Seleccionar empresa..."
+    },
+    "contactId": {
+      "label": "Contacto Principal",
+      "description": "Contacto principal",
+      "placeholder": "Seleccionar contacto..."
+    },
+    "pipelineId": {
+      "label": "Pipeline",
+      "description": "Pipeline de ventas",
+      "placeholder": "Seleccionar pipeline..."
+    },
+    "stageId": {
+      "label": "Etapa",
+      "description": "Etapa actual",
+      "placeholder": "ID de etapa..."
+    },
+    "amount": {
+      "label": "Monto",
+      "description": "Valor del trato",
+      "placeholder": "0.00"
+    },
+    "currency": {
+      "label": "Moneda",
+      "description": "Código de moneda",
+      "placeholder": "Seleccionar moneda..."
+    },
+    "probability": {
+      "label": "Probabilidad (%)",
+      "description": "Probabilidad de ganar",
+      "placeholder": "0"
+    },
+    "expectedRevenue": {
+      "label": "Ingresos Esperados",
+      "description": "Ingresos esperados calculados"
+    },
+    "closeDate": {
+      "label": "Fecha de Cierre",
+      "description": "Fecha esperada de cierre",
+      "placeholder": "Seleccionar fecha..."
+    },
+    "type": {
+      "label": "Tipo",
+      "description": "Tipo de oportunidad",
+      "placeholder": "Seleccionar tipo..."
+    },
+    "source": {
+      "label": "Fuente",
+      "description": "Fuente de la oportunidad",
+      "placeholder": "Seleccionar fuente..."
+    },
+    "status": {
+      "label": "Estado",
+      "description": "Estado actual",
+      "placeholder": "Seleccionar estado..."
+    },
+    "assignedTo": {
+      "label": "Asignado a",
+      "description": "Representante de ventas",
+      "placeholder": "Seleccionar usuario..."
+    }
+  },
+  "options": {
+    "type": {
+      "new_business": "Nuevo Negocio",
+      "existing_business": "Negocio Existente",
+      "renewal": "Renovación",
+      "upgrade": "Actualización",
+      "downgrade": "Reducción"
+    },
+    "status": {
+      "open": "Abierta",
+      "won": "Ganada",
+      "lost": "Perdida",
+      "abandoned": "Abandonada"
+    }
+  },
+  "actions": {
+    "create": "Crear Oportunidad",
+    "edit": "Editar Oportunidad",
+    "delete": "Eliminar Oportunidad",
+    "view": "Ver Oportunidad",
+    "list": "Listar Oportunidades"
+  },
+  "messages": {
+    "created": "Oportunidad creada exitosamente",
+    "updated": "Oportunidad actualizada exitosamente",
+    "deleted": "Oportunidad eliminada exitosamente",
+    "notFound": "Oportunidad no encontrada",
+    "error": "Error al procesar la oportunidad"
+  }
+}