@nextsparkjs/theme-crm 0.1.0-beta.44 → 0.1.0-beta.45

package/entities/notes/api/docs.md

@@ -0,0 +1,135 @@
+# Notes API
+
+Manage notes and comments on CRM records. Notes can be linked to contacts, companies, and opportunities with support for pinning and privacy settings.
+
+## Overview
+
+The Notes API allows you to create, read, update, and delete note records. Notes provide a way to capture important information and comments about CRM entities.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Notes
+`GET /api/v1/notes`
+
+Returns a paginated list of notes.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `type` (string, optional): Filter by type (general, call, meeting, email, followup, feedback, reminder)
+- `contactId` (string, optional): Filter by contact
+- `companyId` (string, optional): Filter by company
+- `opportunityId` (string, optional): Filter by opportunity
+- `search` (string, optional): Search by title or content
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "note_abc123",
+      "title": "Meeting Summary",
+      "content": "Discussed product roadmap and next steps...",
+      "type": "meeting",
+      "isPinned": true,
+      "isPrivate": false,
+      "contactId": "contact_456",
+      "companyId": "company_xyz",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 234,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Note
+`GET /api/v1/notes/[id]`
+
+Returns a single note by ID.
+
+### Create Note
+`POST /api/v1/notes`
+
+Create a new note record.
+
+**Request Body:**
+```json
+{
+  "title": "Call Notes",
+  "content": "Key points from the call...",
+  "type": "call",
+  "contactId": "contact_456",
+  "isPinned": false,
+  "isPrivate": false
+}
+```
+
+### Update Note
+`PATCH /api/v1/notes/[id]`
+
+Update an existing note. Supports partial updates.
+
+### Delete Note
+`DELETE /api/v1/notes/[id]`
+
+Delete a note record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | text | No | Note title (optional) |
+| content | textarea | Yes | Note content |
+| type | select | No | Type: general, call, meeting, email, followup, feedback, reminder |
+| isPinned | boolean | No | Is note pinned/important |
+| isPrivate | boolean | No | Is note private to creator |
+| entityType | select | No | Related entity type: lead, contact, company, opportunity, campaign |
+| entityId | text | No | ID of related entity |
+| contactId | relation | No | Related contact (→ contacts) |
+| companyId | relation | No | Related company (→ companies) |
+| opportunityId | relation | No | Related opportunity (→ opportunities) |
+| attachments | json | No | Array of attachment objects |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Relationships
+
+| Relation | Entity | Description |
+|----------|--------|-------------|
+| contactId | contacts | Related contact |
+| companyId | companies | Related company |
+| opportunityId | opportunities | Related opportunity |
+
+## Features
+
+- **Searchable**: title, content
+- **Sortable**: Most fields
+- **Privacy**: Private notes only visible to creator
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Note doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Contacts](/api/v1/contacts)** - Related contact
+- **[Companies](/api/v1/companies)** - Related company
+- **[Opportunities](/api/v1/opportunities)** - Related opportunity

package/entities/notes/api/presets.ts

@@ -0,0 +1,115 @@
+/**
+ * API Presets for Notes Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage notes linked to contacts, companies, and opportunities',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Notes',
+      description: 'Get all notes with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-pinned',
+      title: 'List Pinned Notes',
+      description: 'Get all pinned notes',
+      method: 'GET',
+      params: {
+        isPinned: 'true'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-type',
+      title: 'List by Type',
+      description: 'Get notes of a specific type',
+      method: 'GET',
+      params: {
+        type: '{{type}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-contact',
+      title: 'List by Contact',
+      description: 'Get notes for a specific contact',
+      method: 'GET',
+      params: {
+        contactId: '{{contactId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-company',
+      title: 'List by Company',
+      description: 'Get notes for a specific company',
+      method: 'GET',
+      params: {
+        companyId: '{{companyId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-opportunity',
+      title: 'List by Opportunity',
+      description: 'Get notes for a specific opportunity',
+      method: 'GET',
+      params: {
+        opportunityId: '{{opportunityId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'search-notes',
+      title: 'Search Notes',
+      description: 'Search notes by content',
+      method: 'GET',
+      params: {
+        search: '{{searchTerm}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-note',
+      title: 'Create Note',
+      description: 'Create a new note',
+      method: 'POST',
+      payload: {
+        content: 'Note content here...',
+        type: 'general'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'pin-note',
+      title: 'Pin Note',
+      description: 'Pin a note',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        isPinned: true
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-note',
+      title: 'Delete Note',
+      description: 'Delete a note record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/opportunities/api/docs.md

@@ -0,0 +1,151 @@
+# Opportunities API
+
+Manage sales opportunities in the pipeline. Opportunities track deals from initial contact through close, with pipeline stages, amounts, and probabilities.
+
+## Overview
+
+The Opportunities API allows you to create, read, update, and delete opportunity records. Opportunities represent potential sales deals and are linked to companies, contacts, and pipelines.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Opportunities
+`GET /api/v1/opportunities`
+
+Returns a paginated list of opportunities.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `status` (string, optional): Filter by status (open, won, lost, abandoned)
+- `companyId` (string, optional): Filter by company
+- `pipelineId` (string, optional): Filter by pipeline
+- `search` (string, optional): Search by name
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "opp_abc123",
+      "name": "Enterprise License Deal",
+      "companyId": "company_xyz",
+      "contactId": "contact_456",
+      "pipelineId": "pipeline_001",
+      "stageId": "stage_negotiation",
+      "amount": 50000,
+      "currency": "USD",
+      "probability": 75,
+      "expectedRevenue": 37500,
+      "closeDate": "2024-03-15",
+      "status": "open",
+      "assignedTo": "user_789",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 28,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Opportunity
+`GET /api/v1/opportunities/[id]`
+
+Returns a single opportunity by ID.
+
+### Create Opportunity
+`POST /api/v1/opportunities`
+
+Create a new opportunity record.
+
+**Request Body:**
+```json
+{
+  "name": "New Product Launch",
+  "companyId": "company_xyz",
+  "pipelineId": "pipeline_001",
+  "stageId": "stage_discovery",
+  "amount": 25000,
+  "currency": "USD",
+  "probability": 30,
+  "closeDate": "2024-06-30",
+  "type": "new_business"
+}
+```
+
+### Update Opportunity
+`PATCH /api/v1/opportunities/[id]`
+
+Update an existing opportunity. Supports partial updates.
+
+### Delete Opportunity
+`DELETE /api/v1/opportunities/[id]`
+
+Delete an opportunity record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | text | Yes | Opportunity name or title |
+| companyId | relation | Yes | Company (→ companies) |
+| contactId | relation | No | Primary contact (→ contacts) |
+| pipelineId | relation | Yes | Pipeline (→ pipelines) |
+| stageId | text | Yes | Current stage in pipeline |
+| amount | number | Yes | Deal amount value |
+| currency | select | No | Currency: USD, EUR, GBP, MXN, etc. |
+| probability | number | No | Win probability percentage (0-100) |
+| expectedRevenue | number | Auto | Calculated: amount × probability |
+| closeDate | date | Yes | Expected or actual close date |
+| type | select | No | Type: new_business, existing_business, renewal, upgrade, downgrade |
+| source | select | No | Source: web, referral, cold_call, etc. |
+| competitor | text | No | Main competitor for this deal |
+| status | select | No | Status: open, won, lost, abandoned |
+| lostReason | text | No | Reason if opportunity was lost |
+| assignedTo | user | No | Sales rep assigned |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Relationships
+
+| Relation | Entity | Description |
+|----------|--------|-------------|
+| companyId | companies | Company this opportunity is for |
+| contactId | contacts | Primary contact for this deal |
+| pipelineId | pipelines | Pipeline this opportunity is in |
+
+## Features
+
+- **Searchable**: name, competitor, lost reason
+- **Sortable**: Most fields
+- **Bulk Operations**: Supported
+- **Import/Export**: Supported
+- **Metadata**: Supported
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Opportunity doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Companies](/api/v1/companies)** - Associated company
+- **[Contacts](/api/v1/contacts)** - Primary contact
+- **[Pipelines](/api/v1/pipelines)** - Pipeline configuration
+- **[Activities](/api/v1/activities)** - Related activities
+- **[Notes](/api/v1/notes)** - Notes about this opportunity

package/entities/opportunities/api/presets.ts

@@ -0,0 +1,151 @@
+/**
+ * API Presets for Opportunities Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage sales opportunities with pipeline tracking',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Opportunities',
+      description: 'Get all opportunities with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-open',
+      title: 'List Open Opportunities',
+      description: 'Get all open opportunities',
+      method: 'GET',
+      params: {
+        status: 'open'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-won',
+      title: 'List Won Opportunities',
+      description: 'Get all won opportunities',
+      method: 'GET',
+      params: {
+        status: 'won'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-company',
+      title: 'List by Company',
+      description: 'Get opportunities for a specific company',
+      method: 'GET',
+      params: {
+        companyId: '{{companyId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-pipeline',
+      title: 'List by Pipeline',
+      description: 'Get opportunities in a specific pipeline',
+      method: 'GET',
+      params: {
+        pipelineId: '{{pipelineId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-closing-soon',
+      title: 'List Closing Soon',
+      description: 'Get opportunities sorted by close date',
+      method: 'GET',
+      params: {
+        status: 'open',
+        sortBy: 'closeDate',
+        sortOrder: 'asc'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'list-high-value',
+      title: 'List High Value',
+      description: 'Get opportunities sorted by amount',
+      method: 'GET',
+      params: {
+        status: 'open',
+        sortBy: 'amount',
+        sortOrder: 'desc'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'create-opportunity',
+      title: 'Create New Opportunity',
+      description: 'Create an opportunity with sample data',
+      method: 'POST',
+      payload: {
+        name: 'Sample Deal',
+        companyId: '{{companyId}}',
+        pipelineId: '{{pipelineId}}',
+        stageId: 'discovery',
+        amount: 10000,
+        currency: 'USD',
+        closeDate: '2024-12-31'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-stage',
+      title: 'Update Stage',
+      description: 'Move opportunity to a new stage',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        stageId: '{{newStageId}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'mark-won',
+      title: 'Mark as Won',
+      description: 'Mark opportunity as won',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'won'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'mark-lost',
+      title: 'Mark as Lost',
+      description: 'Mark opportunity as lost with reason',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'lost',
+        lostReason: '{{reason}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-opportunity',
+      title: 'Delete Opportunity',
+      description: 'Delete an opportunity record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/pipelines/api/docs.md

@@ -0,0 +1,145 @@
+# Pipelines API
+
+Manage sales pipelines with customizable stages. Pipelines define the workflow for tracking opportunities from initial contact to close.
+
+## Overview
+
+The Pipelines API allows you to create, read, update, and delete pipeline configurations. Pipelines contain stages that define the sales process and are used by opportunities to track progress.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Pipelines
+`GET /api/v1/pipelines`
+
+Returns a paginated list of pipelines.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `type` (string, optional): Filter by type (sales, support, project, custom)
+- `isActive` (boolean, optional): Filter by active status
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "pipeline_abc123",
+      "name": "Sales Pipeline",
+      "description": "Main sales process",
+      "type": "sales",
+      "isDefault": true,
+      "isActive": true,
+      "stages": [
+        {"id": "discovery", "name": "Discovery", "probability": 10, "order": 1},
+        {"id": "proposal", "name": "Proposal", "probability": 30, "order": 2},
+        {"id": "negotiation", "name": "Negotiation", "probability": 60, "order": 3},
+        {"id": "closed", "name": "Closed Won", "probability": 100, "order": 4}
+      ],
+      "dealRottenDays": 30,
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 3,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Pipeline
+`GET /api/v1/pipelines/[id]`
+
+Returns a single pipeline by ID.
+
+### Create Pipeline
+`POST /api/v1/pipelines`
+
+Create a new pipeline configuration.
+
+**Request Body:**
+```json
+{
+  "name": "New Sales Pipeline",
+  "description": "Custom sales process",
+  "type": "sales",
+  "isActive": true,
+  "stages": [
+    {"id": "lead", "name": "Lead", "probability": 5, "order": 1},
+    {"id": "qualified", "name": "Qualified", "probability": 25, "order": 2},
+    {"id": "demo", "name": "Demo", "probability": 50, "order": 3},
+    {"id": "proposal", "name": "Proposal", "probability": 75, "order": 4},
+    {"id": "won", "name": "Won", "probability": 100, "order": 5}
+  ],
+  "dealRottenDays": 14
+}
+```
+
+### Update Pipeline
+`PATCH /api/v1/pipelines/[id]`
+
+Update an existing pipeline. Supports partial updates.
+
+### Delete Pipeline
+`DELETE /api/v1/pipelines/[id]`
+
+Delete a pipeline configuration. Note: Cannot delete pipelines with active opportunities.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | text | Yes | Pipeline name |
+| description | textarea | No | Pipeline description |
+| type | select | No | Type: sales, support, project, custom |
+| isDefault | boolean | No | Is this the default pipeline |
+| isActive | boolean | No | Is pipeline currently active |
+| stages | json | Yes | Array of stage objects |
+| dealRottenDays | number | No | Days until deal is considered stale |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Stage Object Structure
+
+Each stage in the `stages` array should have:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| id | string | Unique stage identifier |
+| name | string | Display name |
+| probability | number | Win probability percentage |
+| order | number | Sort order |
+| color | string | Optional hex color for UI |
+
+## Features
+
+- **Searchable**: name, description
+- **Sortable**: name, type, isDefault, isActive
+
+## Permissions
+
+- **Create/Update/Delete**: Owner only
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions (owner only) |
+| 404 | Not Found - Pipeline doesn't exist |
+| 409 | Conflict - Cannot delete pipeline with active opportunities |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Opportunities](/api/v1/opportunities)** - Deals using this pipeline