# Integration Specialist Memory - tOS Project

## Project Structure
- **API Location**: `/apps/api/src/`
- **Integrations Module**: `/apps/api/src/modules/integrations/`
- **Connectors**: `/apps/api/src/modules/integrations/connectors/`

## Phase 3 Connector Implementation (Completed)

### Base Infrastructure
- `base-connector.ts`: Abstract base class with axios, retry logic, rate limiting
- `errors/integration.errors.ts`: Custom error classes (Auth, Connection, RateLimit, API, Config, Validation)

### Implemented Connectors

#### PlentyONE (`/connectors/plentyone/`)
- **Auth**: OAuth2 Client Credentials flow
- **Token Management**: Auto-refresh with 5-minute buffer
- **Endpoints**: Orders, Stock, Statistics/Revenue
- **Rate Limiting**: 60s timeout (PlentyONE can be slow)
- **API Base**: `{baseUrl}/rest`

#### ZULIP (`/connectors/zulip/`)
- **Auth**: Basic Auth (email + API key)
- **Endpoints**: Messages, Streams, Users
- **API Base**: `{baseUrl}/api/v1`
- **Note**: Form-encoded POST requests for some endpoints

#### Todoist (`/connectors/todoist/`)
- **Auth**: Bearer Token
- **Endpoints**: Tasks, Projects, Sections, Labels
- **API Base**: `https://api.todoist.com/rest/v2`
- **Note**: Uses X-Request-Id header for idempotency

#### FreeScout (`/connectors/freescout/`)
- **Auth**: API Key via `X-FreeScout-API-Key` header
- **Endpoints**: Conversations, Mailboxes, Customers, Tags
- **API Base**: `{baseUrl}/api`
- **API Docs**: https://github.com/freescout-helpdesk/freescout/wiki/API

#### Nextcloud (`/connectors/nextcloud/`)
- **Auth**: Basic Auth (username + app-password)
- **Endpoints**: WebDAV Files, OCS Share API, CalDAV Calendar (basic)
- **API Bases**: `{baseUrl}/remote.php/dav/files/{user}` (WebDAV), `{baseUrl}/ocs/v2.php` (OCS)
- **Note**: WebDAV uses PROPFIND/MKCOL/MOVE/COPY; OCS needs `OCS-APIRequest: true` header

#### ecoDMS (`/connectors/ecodms/`)
- **Auth**: Session-based (login returns session ID, use `X-Session-Id` header)
- **Endpoints**: Documents, Folders, Classifications, Search
- **API Base**: `{baseUrl}/api/v1`
- **Note**: Session auto-refresh before expiry; supports file upload with FormData

## Environment Variables

```bash
# PlentyONE
PLENTYONE_BASE_URL=
PLENTYONE_CLIENT_ID=
PLENTYONE_CLIENT_SECRET=

# ZULIP
ZULIP_BASE_URL=
ZULIP_EMAIL=
ZULIP_API_KEY=

# Todoist
TODOIST_API_TOKEN=

# FreeScout
FREESCOUT_API_URL=
FREESCOUT_API_KEY=

# Nextcloud
NEXTCLOUD_URL=
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=

# ecoDMS
ECODMS_API_URL=
ECODMS_USERNAME=
ECODMS_PASSWORD=
ECODMS_API_VERSION=v1
```

## Key Patterns

### Retry Logic
- Exponential backoff with jitter (0.5-1.5x multiplier)
- Default: 3 retries, 1s initial delay, 30s max delay
- Retry on: 429, 500, 502, 503, 504

### Error Handling
- `IntegrationConnectionError`: Network issues (retryable)
- `IntegrationAuthError`: 401 responses (not retryable)
- `IntegrationRateLimitError`: 429 responses (retryable after delay)
- `IntegrationApiError`: Other API errors (retryable if 5xx)

### Module Structure
Each connector follows pattern:
1. `{name}.types.ts` - TypeScript interfaces
2. `{name}.connector.ts` - Low-level API client
3. `{name}.service.ts` - Business logic layer
4. `{name}.controller.ts` - HTTP endpoints
5. `{name}.module.ts` - NestJS module
6. `dto/*.dto.ts` - Request/Response DTOs

## API Endpoints

```
GET  /integrations - Overview all integrations
GET  /integrations/:type/status - Integration status
GET  /integrations/:type/health - Health check

POST /integrations/plentyone/test
GET  /integrations/plentyone/orders
GET  /integrations/plentyone/orders/:id
GET  /integrations/plentyone/stock
GET  /integrations/plentyone/stats

POST /integrations/zulip/test
GET  /integrations/zulip/messages
POST /integrations/zulip/messages
GET  /integrations/zulip/streams
GET  /integrations/zulip/users

POST /integrations/todoist/test
GET  /integrations/todoist/tasks
POST /integrations/todoist/tasks
PUT  /integrations/todoist/tasks/:id
DELETE /integrations/todoist/tasks/:id
GET  /integrations/todoist/projects

# FreeScout
POST /integrations/freescout/test
GET  /integrations/freescout/conversations
GET  /integrations/freescout/conversations/:id
POST /integrations/freescout/conversations
POST /integrations/freescout/conversations/:id/reply
GET  /integrations/freescout/mailboxes
GET  /integrations/freescout/customers
GET  /integrations/freescout/tags

# Nextcloud
POST /integrations/nextcloud/test
GET  /integrations/nextcloud/files
GET  /integrations/nextcloud/files/*path
POST /integrations/nextcloud/files/upload
DELETE /integrations/nextcloud/files/*path
GET  /integrations/nextcloud/calendar/events

# ecoDMS
POST /integrations/ecodms/test
GET  /integrations/ecodms/documents
GET  /integrations/ecodms/documents/:id
POST /integrations/ecodms/documents/search
GET  /integrations/ecodms/documents/:id/download
GET  /integrations/ecodms/folders
GET  /integrations/ecodms/classifications
```

## Dependencies
- `axios`: ^1.6.0 (HTTP client)
- axios types included in axios package

## Notes
- All connectors check `isConfigured()` before operations
- `getMissingConfig()` returns list of missing env vars
- Logging in development mode by default
- All API responses transformed to DTOs