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

package/entities/activities/api/docs.md

@@ -0,0 +1,146 @@
+# Activities API
+
+Manage tasks and activities related to CRM records. Activities track calls, emails, meetings, and other interactions with contacts, companies, and opportunities.
+
+## Overview
+
+The Activities API allows you to create, read, update, and delete activity records. Activities help teams track their interactions and tasks across all CRM entities.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Activities
+`GET /api/v1/activities`
+
+Returns a paginated list of activities.
+
+**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 (call, email, meeting, task, note, demo, presentation)
+- `status` (string, optional): Filter by status (scheduled, in_progress, completed, cancelled, overdue)
+- `contactId` (string, optional): Filter by contact
+- `companyId` (string, optional): Filter by company
+- `opportunityId` (string, optional): Filter by opportunity
+- `search` (string, optional): Search by subject
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "activity_abc123",
+      "type": "meeting",
+      "subject": "Product Demo",
+      "description": "Demo of new features",
+      "status": "scheduled",
+      "priority": "high",
+      "dueDate": "2024-01-20T14:00:00Z",
+      "duration": 60,
+      "location": "Zoom",
+      "contactId": "contact_456",
+      "companyId": "company_xyz",
+      "assignedTo": "user_789",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 156,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Activity
+`GET /api/v1/activities/[id]`
+
+Returns a single activity by ID.
+
+### Create Activity
+`POST /api/v1/activities`
+
+Create a new activity record.
+
+**Request Body:**
+```json
+{
+  "type": "call",
+  "subject": "Follow-up call",
+  "description": "Discuss proposal",
+  "status": "scheduled",
+  "priority": "medium",
+  "dueDate": "2024-01-22T10:00:00Z",
+  "duration": 30,
+  "contactId": "contact_456"
+}
+```
+
+### Update Activity
+`PATCH /api/v1/activities/[id]`
+
+Update an existing activity. Supports partial updates.
+
+### Delete Activity
+`DELETE /api/v1/activities/[id]`
+
+Delete an activity record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| type | select | Yes | Type: call, email, meeting, task, note, demo, presentation |
+| subject | text | Yes | Activity subject or title |
+| description | textarea | No | Detailed description |
+| status | select | No | Status: scheduled, in_progress, completed, cancelled, overdue |
+| priority | select | No | Priority: low, medium, high, urgent |
+| dueDate | datetime | No | When activity is due |
+| completedAt | datetime | Auto | When activity was completed |
+| duration | number | No | Duration in minutes |
+| outcome | textarea | No | Activity outcome or result |
+| location | text | No | Location for meetings |
+| contactId | relation | No | Related contact (→ contacts) |
+| companyId | relation | No | Related company (→ companies) |
+| opportunityId | relation | No | Related opportunity (→ opportunities) |
+| assignedTo | user | No | User assigned |
+| 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**: subject, description, outcome, location
+- **Sortable**: Most fields
+- **Bulk Operations**: 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 - Activity 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/activities/api/presets.ts

@@ -0,0 +1,132 @@
+/**
+ * API Presets for Activities Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Track calls, meetings, tasks, and emails',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Activities',
+      description: 'Get all activities with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-upcoming',
+      title: 'List Upcoming',
+      description: 'Get scheduled activities sorted by due date',
+      method: 'GET',
+      params: {
+        status: 'scheduled',
+        sortBy: 'dueDate',
+        sortOrder: 'asc'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'list-overdue',
+      title: 'List Overdue',
+      description: 'Get overdue activities',
+      method: 'GET',
+      params: {
+        status: 'overdue'
+      },
+      tags: ['read', 'filter', 'priority']
+    },
+    {
+      id: 'list-by-type',
+      title: 'List by Type',
+      description: 'Get activities of a specific type',
+      method: 'GET',
+      params: {
+        type: '{{type}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-contact',
+      title: 'List by Contact',
+      description: 'Get activities for a specific contact',
+      method: 'GET',
+      params: {
+        contactId: '{{contactId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-company',
+      title: 'List by Company',
+      description: 'Get activities for a specific company',
+      method: 'GET',
+      params: {
+        companyId: '{{companyId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-opportunity',
+      title: 'List by Opportunity',
+      description: 'Get activities for a specific opportunity',
+      method: 'GET',
+      params: {
+        opportunityId: '{{opportunityId}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'create-call',
+      title: 'Create Call',
+      description: 'Create a new call activity',
+      method: 'POST',
+      payload: {
+        type: 'call',
+        subject: 'Follow-up call',
+        status: 'scheduled',
+        priority: 'medium'
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'create-meeting',
+      title: 'Create Meeting',
+      description: 'Create a new meeting activity',
+      method: 'POST',
+      payload: {
+        type: 'meeting',
+        subject: 'Meeting',
+        status: 'scheduled',
+        duration: 60
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'mark-completed',
+      title: 'Mark Completed',
+      description: 'Mark an activity as completed',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'completed'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-activity',
+      title: 'Delete Activity',
+      description: 'Delete an activity record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

package/entities/campaigns/api/docs.md

@@ -0,0 +1,140 @@
+# Campaigns API
+
+Manage marketing campaigns with budget tracking, lead generation metrics, and ROI analysis.
+
+## Overview
+
+The Campaigns API allows you to create, read, update, and delete campaign records. Campaigns track marketing efforts and their effectiveness in generating leads and revenue.
+
+## Authentication
+
+All endpoints require authentication via:
+- **Session cookie** (for browser-based requests)
+- **API Key** header (for server-to-server requests)
+
+## Endpoints
+
+### List Campaigns
+`GET /api/v1/campaigns`
+
+Returns a paginated list of campaigns.
+
+**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 (email, social, event, webinar, advertising, content, other)
+- `status` (string, optional): Filter by status (planned, active, paused, completed, cancelled)
+- `search` (string, optional): Search by name, objective
+- `sortBy` (string, optional): Field to sort by
+- `sortOrder` (string, optional): Sort direction (asc, desc)
+
+**Example Response:**
+```json
+{
+  "data": [
+    {
+      "id": "campaign_abc123",
+      "name": "Q1 Email Campaign",
+      "type": "email",
+      "status": "active",
+      "objective": "Generate leads for new product launch",
+      "startDate": "2024-01-01",
+      "endDate": "2024-03-31",
+      "budget": 10000,
+      "actualCost": 7500,
+      "targetLeads": 500,
+      "actualLeads": 350,
+      "targetRevenue": 100000,
+      "actualRevenue": 75000,
+      "roi": 900,
+      "channel": "email",
+      "assignedTo": "user_456",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 15,
+    "limit": 20,
+    "offset": 0
+  }
+}
+```
+
+### Get Single Campaign
+`GET /api/v1/campaigns/[id]`
+
+Returns a single campaign by ID.
+
+### Create Campaign
+`POST /api/v1/campaigns`
+
+Create a new campaign record.
+
+**Request Body:**
+```json
+{
+  "name": "New Product Launch",
+  "type": "social",
+  "status": "planned",
+  "objective": "Create awareness for new product",
+  "startDate": "2024-04-01",
+  "endDate": "2024-05-31",
+  "budget": 15000,
+  "targetLeads": 300,
+  "channel": "social_media"
+}
+```
+
+### Update Campaign
+`PATCH /api/v1/campaigns/[id]`
+
+Update an existing campaign. Supports partial updates.
+
+### Delete Campaign
+`DELETE /api/v1/campaigns/[id]`
+
+Delete a campaign record.
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | text | Yes | Campaign name |
+| type | select | No | Type: email, social, event, webinar, advertising, content, other |
+| status | select | No | Status: planned, active, paused, completed, cancelled |
+| objective | text | No | Campaign objective |
+| description | textarea | No | Detailed campaign description |
+| startDate | date | Yes | Campaign start date |
+| endDate | date | Yes | Campaign end date |
+| budget | number | No | Campaign budget |
+| actualCost | number | No | Actual cost spent |
+| targetAudience | text | No | Target audience description |
+| targetLeads | number | No | Target number of leads |
+| actualLeads | number | No | Actual leads generated |
+| targetRevenue | number | No | Target revenue to generate |
+| actualRevenue | number | No | Actual revenue generated |
+| roi | number | Auto | Return on investment percentage |
+| channel | select | No | Main channel: email, social_media, web, print, tv, radio, other |
+| assignedTo | user | No | Campaign manager assigned |
+| createdAt | datetime | Auto | Creation timestamp |
+| updatedAt | datetime | Auto | Last update timestamp |
+
+## Features
+
+- **Searchable**: name, objective, description, target audience
+- **Sortable**: Most fields
+- **Metadata**: Supported
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing or invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Campaign doesn't exist |
+| 422 | Validation Error - Invalid data |
+
+## Related APIs
+
+- **[Leads](/api/v1/leads)** - Leads generated by campaigns

package/entities/campaigns/api/presets.ts

@@ -0,0 +1,147 @@
+/**
+ * API Presets for Campaigns Entity
+ */
+
+import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
+
+export default defineApiEndpoint({
+  summary: 'Manage marketing campaigns with budget and ROI tracking',
+  presets: [
+    {
+      id: 'list-all',
+      title: 'List All Campaigns',
+      description: 'Get all campaigns with pagination',
+      method: 'GET',
+      params: {
+        limit: 20
+      },
+      tags: ['read', 'list']
+    },
+    {
+      id: 'list-active',
+      title: 'List Active Campaigns',
+      description: 'Get all active campaigns',
+      method: 'GET',
+      params: {
+        status: 'active'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-planned',
+      title: 'List Planned Campaigns',
+      description: 'Get all planned campaigns',
+      method: 'GET',
+      params: {
+        status: 'planned'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-completed',
+      title: 'List Completed Campaigns',
+      description: 'Get all completed campaigns',
+      method: 'GET',
+      params: {
+        status: 'completed'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-by-type',
+      title: 'List by Type',
+      description: 'Get campaigns of a specific type',
+      method: 'GET',
+      params: {
+        type: '{{type}}'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'list-email',
+      title: 'List Email Campaigns',
+      description: 'Get all email campaigns',
+      method: 'GET',
+      params: {
+        type: 'email'
+      },
+      tags: ['read', 'filter']
+    },
+    {
+      id: 'search-by-name',
+      title: 'Search by Name',
+      description: 'Search campaigns by name',
+      method: 'GET',
+      params: {
+        search: '{{name}}'
+      },
+      tags: ['read', 'search']
+    },
+    {
+      id: 'create-campaign',
+      title: 'Create Campaign',
+      description: 'Create a new campaign',
+      method: 'POST',
+      payload: {
+        name: 'New Campaign',
+        type: 'email',
+        status: 'planned',
+        startDate: '2024-01-01',
+        endDate: '2024-03-31',
+        budget: 5000
+      },
+      tags: ['write', 'create']
+    },
+    {
+      id: 'update-metrics',
+      title: 'Update Metrics',
+      description: 'Update campaign performance metrics',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        actualLeads: '{{leads}}',
+        actualRevenue: '{{revenue}}',
+        actualCost: '{{cost}}'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'activate',
+      title: 'Activate Campaign',
+      description: 'Set campaign status to active',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'active'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'complete',
+      title: 'Complete Campaign',
+      description: 'Mark campaign as completed',
+      method: 'PATCH',
+      pathParams: {
+        id: '{{id}}'
+      },
+      payload: {
+        status: 'completed'
+      },
+      tags: ['write', 'update']
+    },
+    {
+      id: 'delete-campaign',
+      title: 'Delete Campaign',
+      description: 'Delete a campaign record',
+      method: 'DELETE',
+      pathParams: {
+        id: '{{id}}'
+      },
+      tags: ['write', 'delete']
+    }
+  ]
+})

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