@nextsparkjs/theme-crm 0.1.0-beta.1 → 0.1.0-beta.100

package/entities/companies/api/docs.md

@@ -0,0 +1,139 @@
+# Companies API
+
+Manage customer and prospect companies. Companies serve as the central entity linking contacts, opportunities, and activities.
+
+## Overview
+
+The Companies API allows you to create, read, update, and delete company records. Companies represent organizations that your team works with and can be categorized by type (prospect, customer, partner, etc.).
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Companies
+`GET /api/v1/companies`
+
+Returns a paginated list of companies.
+
+**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 (prospect, customer, partner, competitor, vendor, other)
+- `rating` (string, optional): Filter by rating (hot, warm, cold)
+- `search` (string, optional): Search by name, email, industry
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "company_abc123",
+      "name": "Acme Corporation",
+      "legalName": "Acme Corp Inc.",
+      "website": "https://acme.com",
+      "email": "info@acme.com",
+      "phone": "+1-555-0100",
+      "industry": "Technology",
+      "type": "customer",
+      "size": "201-500",
+      "rating": "hot",
+      "country": "US",
+      "assignedTo": "user_456",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 89,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Company
+`GET /api/v1/companies/[id]`
+
+Returns a single company by ID.
+
+### Create Company
+`POST /api/v1/companies`
+
+Create a new company record.
+
+**Request Body:**
+```json
+{
+  "name": "New Tech Inc",
+  "email": "info@newtech.com",
+  "website": "https://newtech.com",
+  "industry": "Software",
+  "type": "prospect",
+  "size": "51-200"
+}
+```
+
+### Update Company
+`PATCH /api/v1/companies/[id]`
+
+Update an existing company. Supports partial updates.
+
+### Delete Company
+`DELETE /api/v1/companies/[id]`
+
+Delete a company record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | text | Yes | Company display name |
+| legalName | text | No | Legal registered name |
+| taxId | text | No | Tax identification number |
+| website | url | No | Company website URL |
+| email | email | No | General company email |
+| phone | text | No | Main phone number |
+| industry | text | No | Industry sector |
+| type | select | No | Type: prospect, customer, partner, competitor, vendor, other |
+| size | select | No | Size: 1-10, 11-50, 51-200, 201-500, 500+ |
+| annualRevenue | number | No | Annual revenue |
+| address | textarea | No | Street address |
+| city | text | No | City |
+| state | text | No | State or province |
+| country | text | No | Country |
+| postalCode | text | No | Postal or ZIP code |
+| logo | url | No | Company logo URL |
+| rating | select | No | Sales rating: hot, warm, cold |
+| assignedTo | user | No | Account manager assigned |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Features
+
+- **Searchable**: name, legal name, tax ID, email, phone, industry, address, city, state, country, postal code
+- **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 - Company doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Contacts](/api/v1/contacts)** - People at this company
+- **[Opportunities](/api/v1/opportunities)** - Sales opportunities
+- **[Activities](/api/v1/activities)** - Activities with this company
+- **[Notes](/api/v1/notes)** - Notes about this company

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