mehmed/teOS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fe305f6fc81b0516de2704770f7bc83a703e9839
teOS/.claude/agent-memory/integration-specialist/MEMORY.md
Flexomatic81 fe305f6fc8 feat: complete tOS project with HR, LEAN, Dashboard and Integrations modules 
Full enterprise web operating system including:
- Next.js 14 frontend with App Router, i18n (DE/EN), shadcn/ui
- NestJS 10 backend with Prisma, JWT auth, Swagger docs
- Keycloak 24 SSO with role-based access control
- HR module (employees, time tracking, absences, org chart)
- LEAN module (3S planning, morning meeting SQCDM, skill matrix)
- Integrations module (PlentyONE, Zulip, Todoist, FreeScout, Nextcloud, ecoDMS, GembaDocs)
- Dashboard with customizable drag & drop widget grid
- Docker Compose infrastructure (PostgreSQL 16, Redis 7, Keycloak 24)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 19:37:55 +01:00

170 lines
5.1 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink