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

5.1 KiB
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/)

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

# 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