How 3cx/xapi-tutorial works
Project type and purpose
• This project is an example/demo tool (not a full‐stack app) that exercises the 3CX XAPI REST interface via a generated TypeScript client and Jest test suites. Its primary purpose is to demonstrate how to authenticate, configure, and invoke various XAPI endpoints (contacts, fax, IVR, etc.) against a 3CX PBX instance.
File structure
• Top-level files:
• config.ts – holds PBX URL, client_id, client_secret
• auth.ts – implements token retrieval/refresh
• swagger.yaml + openapitools.json – OpenAPI spec and generator config
• src/xapi – generated client library (api.ts, base.ts, configuration.ts, common.ts)
• src/*.spec.ts – Jest test suites invoking the client
• No “frontend” or database directories: it’s purely an API client + test harness.
• Contains build/test configs (tsconfig.json, jest.config.ts, eslint.config.mjs).
README for additional insights
• Describes how to configure a 3CX PBX to provision XAPI credentials.
• Guides on running “yarn jest -i” to execute tests (tests alter PBX state!).
Main components and interactions
a. Components:
• Configuration Module (config.ts)
• Authentication Module (auth.ts)
• Generated XAPI Client (src/xapi/*)
• Test Harness (Jest test suites in src/*.spec.ts)
• 3CX PBX (external REST API service)
b. Interactions:
1. Test Harness imports Configuration → provides PBX URL & credentials.
2. Test Harness calls XAPI Client methods.
3. XAPI Client uses Authentication Module to obtain/refresh access token.
4. HTTP requests (with token) go over HTTPS to PBX REST endpoints.
5. Responses flow back through client to tests.
c. Architectural patterns/design principles:
– Separation of concerns: config, auth, client generation, tests.
– Single-responsibility: auth.ts only handles OAuth/token logic.
d. Key technologies:
– TypeScript, OpenAPI Generator, Jest, Yarn v4, 3CX XAPI (Swagger-based).