Windsurf setup

# COR API Development Rules

You are an AI assistant specialized in building integrations with the COR platform APIs.

## COR Platform Overview

COR is a project management platform for agencies and professional services. Three APIs are available:

| API | Base URL | Purpose |
|-----|----------|---------|
| Main API | `https://api.projectcor.com/v1` | Core platform operations |
| Resource Allocation | `https://planner.svc.v2.projectcor.com` | User capacity management |
| Integrations API | `https://integrations.projectcor.com` | External system synchronization |

## Authentication

All APIs use OAuth 2.0 with Bearer tokens. The same token works across all three APIs.

### Token Request (Client Credentials)

```bash
# Encode credentials
echo -n "API_KEY:CLIENT_SECRET" | base64

# Get token
curl -X POST 'https://api.projectcor.com/v1/oauth/token?grant_type=client_credentials' \
  -H 'Authorization: Basic BASE64_CREDENTIALS'
```

### Token Usage

```
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```

### Token Refresh

```bash
curl -X POST 'https://api.projectcor.com/v1/oauth/refreshtoken' \
  -d 'refresh_token=REFRESH_TOKEN'
```

## Main API

### Core Entities

| Entity | Endpoint | Operations |
|--------|----------|------------|
| Clients | `/clients` | GET, POST, PUT |
| Projects | `/projects` | GET, POST, PUT, DELETE |
| Tasks | `/tasks` | GET, POST, PUT, DELETE |
| Hours | `/hours` | GET, POST |
| Users | `/users` | GET, POST, PUT, DELETE |
| Brands | `/brands` | GET, POST, PUT, DELETE |
| Products | `/products` | GET, POST, PUT, DELETE |

### Entity Hierarchy

```
Company
  └── Clients → Brands → Products
        └── Projects → Tasks → Hours
  └── Users (with roles)
```

### User Roles

| role_id | Role |
|---------|------|
| 1 | C-Level |
| 2 | Director |
| 3 | Project Manager |
| 4 | Collaborator |
| 5 | Freelancer |
| 6 | Client |

### Status Values

**Tasks:** `nueva`, `en_proceso`, `estancada`, `finalizada`

**Projects:** `in_process`, `finished`, `suspended`

### Pagination

All list endpoints return paginated responses:

```json
{
  "total": "45",
  "perPage": 20,
  "page": 1,
  "lastPage": 3,
  "data": [...]
}
```

Parameters:
- `page`: Page number (default: 1, set to `false` for all results)
- `perPage`: Items per page (default: 20)

### Filters

Use URL-encoded JSON:

```bash
?filters=%7B%22client_id%22%3A123%2C%22status%22%3A%22in_process%22%7D
```

### Date Format

- Requests: `YYYY-MM-DD`
- Responses: `YYYY-MM-DD HH:mm:ss` or ISO 8601

## Resource Allocation API

Manages user capacity and project assignments.

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/allocation/saveAllocation` | Create allocation |
| PUT | `/allocation/updateAllocation` | Update allocation |
| DELETE | `/allocation/removeAllocation` | Delete allocation |
| GET | `/allocation/getAllocations/{projectId}` | Get project allocations |

### Allocation Object

```json
{
  "userId": 1111,
  "companyId": 1111,
  "email": "user@example.com",
  "resource": {
    "typeId": "Project",
    "entityId": 1111
  },
  "from": "2024-06-01",
  "to": "2024-10-31",
  "assignedByUserId": 11111,
  "allocatedHours": 20
}
```

### Validation Rules

- `allocatedHours` cannot be empty
- `from` must be before `to`
- Date range max: 12 months
- No overlapping allocations for same user/project

### Errors

| Error | Cause |
|-------|-------|
| `InvalidAllocationError` | Invalid data |
| `AllocationAlreadyExistInDatesRangeError` | Overlap exists |
| `UserNotFoundError` | User not found |
| `UserNotHaveWorkDaysError` | No work days |
| `ProjectNotFoundError` | Project not found |
| `AllocationNotFoundError` | Allocation not found |

## Integrations API

Synchronizes external systems with COR via external ID mapping.

### Required Field

All requests must include `metadata.source`:

```json
{
  "metadata": {
    "source": "SALESFORCE"
  },
  "id": "external-id-123",
  "name": "Entity Name"
}
```

### Supported Sources

`JIRA`, `SALESFORCE`, `ADVERTMIND`, `QUICKBOOKS`, `ZAPIER`, `OKTA`, `MICROSOFT_DYNAMICS`, `GITHUB`, `MICROSOFT_TEAMS`, `VBS`, `SAP`, `GLOBANT`

### Integration Entities

| Entity | Operations |
|--------|------------|
| Projects | CREATE, UPDATE, DELETE |
| Clients | CREATE, UPDATE, DELETE |
| Users | CREATE, UPDATE, DELETE, Assign Position |
| Working Time | CREATE, DELETE |
| Contracts | CREATE, UPDATE, DELETE, Attach/Detach Users |
| Workspaces | CREATE, UPDATE |
| Brands | CREATE, UPDATE, DELETE |

### External ID Mapping

1. Send external ID with `metadata.source`
2. COR creates entity and stores mapping
3. Reference external ID in future operations

### Error Codes

| Code | Description |
|------|-------------|
| `ZC001` | Generic Error |
| `ZC002` | Validation Error |
| `ZC003` | API Request Exception |
| `ZC004` | Query Exception |
| `ZC005` | External Request Exception |

## HTTP Status Codes

| Code | Meaning | Action |
|------|---------|--------|
| `200` | Success | - |
| `201` | Created | - |
| `400` | Bad Request | Check required fields |
| `401` | Unauthorized | Refresh token |
| `403` | Forbidden | Check permissions |
| `404` | Not Found | Verify resource ID |
| `422` | Validation Error | Check data format |
| `429` | Rate Limited | Implement backoff |
| `500` | Server Error | Retry with backoff |

## Best Practices

### Security

- Store credentials in environment variables
- Never hardcode tokens in source code
- Implement automatic token refresh

### API Usage

- Always handle pagination on list endpoints
- URL-encode filter JSON objects
- Use correct date format (YYYY-MM-DD)
- Include `metadata.source` on all Integration API calls

### Error Handling

- Check status codes on all responses
- Parse error bodies for specific error types
- Implement exponential backoff for retries

### Resource Allocation

- Validate date ranges before requests
- Check for overlapping allocations
- Ensure users have work days configured