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

package/entities/companies/api/presets.ts

@@ -0,0 +1,107 @@
+/**
+ * API Presets for Companies Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage company/organization records',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Companies',
+      description: 'Get all companies with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-customers',
+      title: 'List Customers',
+      description: 'Get customer companies',
+      method: 'GET',
+      params: {
+        type: 'customer'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-prospects',
+      title: 'List Prospects',
+      description: 'Get prospect companies',
+      method: 'GET',
+      params: {
+        type: 'prospect'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-hot',
+      title: 'List Hot Companies',
+      description: 'Get companies with hot rating',
+      method: 'GET',
+      params: {
+        rating: 'hot'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'filter-by-industry',
+      title: 'Filter by Industry',
+      description: 'Get companies in a specific industry',
+      method: 'GET',
+      params: {
+        industry: '{{industry}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'search-by-name',
+      title: 'Search by Name',
+      description: 'Search companies by name',
+      method: 'GET',
+      params: {
+        search: '{{name}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-company',
+      title: 'Create New Company',
+      description: 'Create a company with sample data',
+      method: 'POST',
+      payload: {
+        name: 'Sample Corp',
+        email: 'info@samplecorp.com',
+        industry: 'Technology',
+        type: 'prospect'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-rating',
+      title: 'Update Rating',
+      description: 'Update the sales rating of a company',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        rating: '{{rating}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-company',
+      title: 'Delete Company',
+      description: 'Delete a company record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/contacts/api/docs.md

@@ -0,0 +1,139 @@
+# Contacts API
+
+Manage people contacts at companies. Contacts can be linked to companies and support social profiles, communication preferences, and contact history.
+
+## Overview
+
+The Contacts API allows you to create, read, update, and delete contact records. Contacts represent people at companies and can be associated with companies, opportunities, and activities.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Contacts
+`GET /api/v1/contacts`
+
+Returns a paginated list of contacts.
+
+**Query Parameters:**
+- `limit` (number, optional): Maximum records to return. Default: 20
+- `offset` (number, optional): Number of records to skip. Default: 0
+- `companyId` (string, optional): Filter by associated company
+- `search` (string, optional): Search by name, email, phone
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "contact_abc123",
+      "firstName": "Jane",
+      "lastName": "Smith",
+      "email": "jane.smith@acme.com",
+      "phone": "+1-555-0100",
+      "mobile": "+1-555-0101",
+      "companyId": "company_xyz",
+      "position": "VP of Sales",
+      "isPrimary": true,
+      "lastContactedAt": "2024-01-15T14:30:00Z",
+      "createdAt": "2024-01-10T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 156,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Contact
+`GET /api/v1/contacts/[id]`
+
+Returns a single contact by ID.
+
+### Create Contact
+`POST /api/v1/contacts`
+
+Create a new contact record.
+
+**Request Body:**
+```json
+{
+  "firstName": "John",
+  "lastName": "Doe",
+  "email": "john.doe@company.com",
+  "phone": "+1-555-0200",
+  "companyId": "company_xyz",
+  "position": "CTO",
+  "preferredChannel": "email"
+}
+```
+
+### Update Contact
+`PATCH /api/v1/contacts/[id]`
+
+Update an existing contact. Supports partial updates.
+
+### Delete Contact
+`DELETE /api/v1/contacts/[id]`
+
+Delete a contact record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| firstName | text | Yes | Contact first name |
+| lastName | text | Yes | Contact last name |
+| email | email | Yes | Email address |
+| phone | text | No | Office phone number |
+| mobile | text | No | Mobile phone number |
+| companyId | relation | No | Associated company (→ companies) |
+| position | text | No | Job position or title |
+| department | text | No | Department in company |
+| isPrimary | boolean | No | Is primary contact for company |
+| birthDate | date | No | Contact birth date |
+| linkedin | url | No | LinkedIn profile URL |
+| twitter | text | No | Twitter/X handle |
+| preferredChannel | select | No | Preferred channel: email, phone, whatsapp, linkedin, slack, other |
+| timezone | text | No | Contact timezone |
+| lastContactedAt | datetime | Auto | Last time contacted |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Relationships
+
+| Relation | Entity | Description |
+|----------|--------|-------------|
+| companyId | companies | Company this contact works at |
+
+## Features
+
+- **Searchable**: first name, last name, email, phone, mobile, position, department
+- **Sortable**: All fields except social profiles
+- **Bulk Operations**: Supported
+- **Import/Export**: Supported
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Contact doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Companies](/api/v1/companies)** - Associated companies
+- **[Activities](/api/v1/activities)** - Activities with this contact
+- **[Notes](/api/v1/notes)** - Notes about this contact
+- **[Opportunities](/api/v1/opportunities)** - Related opportunities

package/entities/contacts/api/presets.ts

@@ -0,0 +1,98 @@
+/**
+ * API Presets for Contacts Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage customer contacts with company associations',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Contacts',
+      description: 'Get all contacts with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-by-company',
+      title: 'List by Company',
+      description: 'Get contacts for a specific company',
+      method: 'GET',
+      params: {
+        companyId: '{{companyId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-primary',
+      title: 'List Primary Contacts',
+      description: 'Get all primary contacts',
+      method: 'GET',
+      params: {
+        isPrimary: 'true'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'search-by-name',
+      title: 'Search by Name',
+      description: 'Search contacts by name',
+      method: 'GET',
+      params: {
+        search: '{{name}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'search-by-email',
+      title: 'Search by Email',
+      description: 'Search contacts by email',
+      method: 'GET',
+      params: {
+        search: '{{email}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-contact',
+      title: 'Create New Contact',
+      description: 'Create a contact with sample data',
+      method: 'POST',
+      payload: {
+        firstName: 'Jane',
+        lastName: 'Doe',
+        email: 'jane.doe@sample.com',
+        position: 'Manager',
+        preferredChannel: 'email'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-contact',
+      title: 'Update Contact',
+      description: 'Update contact information',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        phone: '{{phone}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-contact',
+      title: 'Delete Contact',
+      description: 'Delete a contact record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/leads/api/docs.md

@@ -0,0 +1,132 @@
+# Leads API
+
+Manage prospective customers before conversion. Leads are team-shared and support full CRUD operations with import/export.
+
+## Overview
+
+The Leads API allows you to create, read, update, and delete lead records. Leads represent potential customers in the early stages of the sales funnel before they become contacts or opportunities.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Leads
+`GET /api/v1/leads`
+
+Returns a paginated list of leads.
+
+**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 (new, contacted, qualified, proposal, negotiation, converted, lost)
+- `source` (string, optional): Filter by lead source
+- `search` (string, optional): Search term for company name, contact name, email
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "lead_abc123",
+      "companyName": "Acme Corp",
+      "contactName": "John Smith",
+      "email": "john@acme.com",
+      "phone": "+1-555-0100",
+      "source": "web",
+      "status": "qualified",
+      "score": 75,
+      "industry": "Technology",
+      "assignedTo": "user_456",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Lead
+`GET /api/v1/leads/[id]`
+
+Returns a single lead by ID.
+
+### Create Lead
+`POST /api/v1/leads`
+
+Create a new lead record.
+
+**Request Body:**
+```json
+{
+  "companyName": "New Prospect Inc",
+  "contactName": "Jane Doe",
+  "email": "jane@newprospect.com",
+  "phone": "+1-555-0200",
+  "source": "referral",
+  "status": "new",
+  "industry": "Healthcare",
+  "companySize": "51-200"
+}
+```
+
+### Update Lead
+`PATCH /api/v1/leads/[id]`
+
+Update an existing lead. Supports partial updates.
+
+### Delete Lead
+`DELETE /api/v1/leads/[id]`
+
+Delete a lead record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| companyName | text | Yes | Name of the prospect company |
+| contactName | text | Yes | Name of the contact person |
+| email | email | Yes | Email address |
+| phone | text | No | Phone number |
+| website | url | No | Company website |
+| source | select | No | Lead source: web, referral, cold_call, trade_show, social_media, email, advertising, partner, other |
+| status | select | No | Status: new, contacted, qualified, proposal, negotiation, converted, lost |
+| score | number | No | Lead score (0-100) |
+| industry | text | No | Industry sector |
+| companySize | select | No | Company size: 1-10, 11-50, 51-200, 201-500, 500+ |
+| budget | number | No | Estimated budget amount |
+| assignedTo | user | No | Sales rep assigned |
+| notes | textarea | No | Internal notes |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Features
+
+- **Searchable**: company name, contact name, email, industry, notes
+- **Sortable**: All fields except notes
+- **Bulk Operations**: Supported
+- **Import/Export**: Supported
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Lead doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Contacts](/api/v1/contacts)** - Convert leads to contacts
+- **[Companies](/api/v1/companies)** - Company records
+- **[Opportunities](/api/v1/opportunities)** - Sales opportunities

package/entities/leads/api/presets.ts

@@ -0,0 +1,109 @@
+/**
+ * API Presets for Leads Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage prospective customers before conversion',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Leads',
+      description: 'Get all leads with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-new',
+      title: 'List New Leads',
+      description: 'Get leads with status "new"',
+      method: 'GET',
+      params: {
+        status: 'new'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-qualified',
+      title: 'List Qualified Leads',
+      description: 'Get leads with status "qualified"',
+      method: 'GET',
+      params: {
+        status: 'qualified'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-hot',
+      title: 'List Hot Leads',
+      description: 'Get leads sorted by score (highest first)',
+      method: 'GET',
+      params: {
+        sortBy: 'score',
+        sortOrder: 'desc'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'search-by-company',
+      title: 'Search by Company',
+      description: 'Search leads by company name',
+      method: 'GET',
+      params: {
+        search: '{{companyName}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'filter-by-source',
+      title: 'Filter by Source',
+      description: 'Get leads from a specific source',
+      method: 'GET',
+      params: {
+        source: '{{source}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'create-lead',
+      title: 'Create New Lead',
+      description: 'Create a lead with sample data',
+      method: 'POST',
+      payload: {
+        companyName: 'Sample Company',
+        contactName: 'John Doe',
+        email: 'john@sample.com',
+        status: 'new',
+        source: 'web'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-status',
+      title: 'Update Lead Status',
+      description: 'Update the status of a lead',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: '{{newStatus}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-lead',
+      title: 'Delete Lead',
+      description: 'Delete a lead record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})