86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
3CX TAPI is a dual-component integration that bridges the 3CX VoIP telephony web client with a CPA project management suite (CP Solutions) and a time tracking system (ZeitConsens). It is deployed as a Tampermonkey UserScript (client) communicating with a self-hosted ASP.NET Core API (server).
|
||
|
|
|
||
|
|
## Repository Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
/
|
||
|
|
├── client/ # TypeScript UserScript (Tampermonkey)
|
||
|
|
├── server/ # C# ASP.NET Core 10.0 REST API
|
||
|
|
└── 3CX_TAPI.user.js # Built distribution file (committed artifact)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Client Commands
|
||
|
|
|
||
|
|
All commands run from `client/`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run build # Production webpack build → dist/3CX TAPI.prod.user.js
|
||
|
|
npm run dev # Development build with live reload
|
||
|
|
npm run lint # ESLint on TypeScript/JavaScript sources
|
||
|
|
npm run anylize # Build with webpack-bundle-analyzer
|
||
|
|
```
|
||
|
|
|
||
|
|
After building, copy the output to the repo root:
|
||
|
|
```bash
|
||
|
|
cp "client/dist/3CX TAPI.prod.user.js" 3CX_TAPI.user.js
|
||
|
|
```
|
||
|
|
|
||
|
|
The root `3CX_TAPI.user.js` is the committed distribution artifact installed via Tampermonkey.
|
||
|
|
|
||
|
|
## Server Commands
|
||
|
|
|
||
|
|
All commands run from `server/src/CPATapi.Server/`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
dotnet build # Debug build
|
||
|
|
dotnet build -c Release # Release build
|
||
|
|
dotnet publish -c Release -o /app/publish # Publish for deployment
|
||
|
|
docker build -f Dockerfile -t cpatapi-server . # Docker image
|
||
|
|
```
|
||
|
|
|
||
|
|
No automated tests exist — only manual testing and client-side linting.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Client (`client/src/`)
|
||
|
|
|
||
|
|
A Tampermonkey UserScript injected into the 3CX web UI at `https://192.168.0.154:5001/*` and `https://cpsolution.my3cx.at:5001/*`. Entry point: `src/index.js`.
|
||
|
|
|
||
|
|
Four main modules:
|
||
|
|
|
||
|
|
- **`search.ts`** — Autocomplete contact lookup box injected near the call button. Debounces input and calls `GET /search?query=...`. On selection, dials the contact via 3CX.
|
||
|
|
- **`call-history.ts`** — Monitors 3CX call history entries, does reverse lookup via `GET /callerid/{number}`, and adds a "PM Zeitbuchung" button that opens the Domizil PM time booking system with pre-filled metadata (contact ID, timestamp, duration).
|
||
|
|
- **`call-notification.ts`** — Enriches incoming call GM notifications with contact name/medium fetched from TAPI directory.
|
||
|
|
- **`status.ts`** — Polls `GET /availability/{user}` every 30 seconds and auto-syncs 3CX presence status with ZeitConsens login state (odd stamp count = logged in, even = logged out). User settings (username, enabled, status IDs) persist via `GM.setValue`.
|
||
|
|
|
||
|
|
API base URL is configured in `src/config.ts` (`Config.tapi_server_url`).
|
||
|
|
UserScript metadata (match URLs, GM grants, CORS) is in `config/metadata.cjs`.
|
||
|
|
|
||
|
|
### Server (`server/src/CPATapi.Server/`)
|
||
|
|
|
||
|
|
ASP.NET Core 10.0 Web API using Dapper for SQL Server queries. Deployed as a Docker Linux container exposing port 8080.
|
||
|
|
|
||
|
|
**API Endpoints:**
|
||
|
|
|
||
|
|
| Endpoint | Description |
|
||
|
|
|---|---|
|
||
|
|
| `GET /search?query=` | Splits query into terms, searches `CP_TAPI_DIRECTORY` by name or number (top 10) |
|
||
|
|
| `GET /contact` | Returns all contacts from `CP_TAPI_DIRECTORY` |
|
||
|
|
| `GET /callerid/{number}` | Reverse lookup: extracts last 5 digits, returns first matching contact or 404 |
|
||
|
|
| `GET /availability/users` | Lists active users from `MA_DATEN` |
|
||
|
|
| `GET /availability/{user}` | Counts today's stamps in `BU` table; odd count = logged in |
|
||
|
|
|
||
|
|
**Data flow:** Controllers → Repository interfaces → Dapper repositories → SQL Server.
|
||
|
|
|
||
|
|
Two connection strings in `appsettings.json`:
|
||
|
|
- `"Tapi"` — contacts database (`CP_TAPI_DIRECTORY` table)
|
||
|
|
- `"ZeitConsens"` — time tracking database (`MA_DATEN`, `BU` tables)
|
||
|
|
|
||
|
|
Logging uses Serilog with client IP, correlation ID, and user-agent enrichment.
|