Tahoon API - Feature Inventory¶

Overview¶

This document provides a comprehensive inventory of all features, endpoints, and capabilities in the Psyter Shared API (Tahoon API). Each feature is categorized, documented with dependencies, and assessed for completeness.

Feature Categories¶

1. Authentication & Authorization
2. User Management
3. Care Provider Discovery
4. Scheduling & Availability
5. Session Booking
6. Video Conferencing Integration
7. Notifications
8. Security Features
9. Configuration Management

1. Authentication & Authorization¶

1.1 OAuth 2.0 Token Generation¶

Endpoint: POST /api/auth/token

Purpose: Generate JWT access token for organization-level API access

Status: ✅ Fully Implemented

Request Parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| grant_type | string | ✅ | Must be “password” |
| access_key | string | ✅ | Organization API key |

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

Features:
- ✅ OAuth 2.0 password grant flow
- ✅ JWT token generation
- ✅ 24-hour token expiration
- ✅ Organization-specific claims (OrganizationId, SharedAPIKey)
- ❌ Token refresh endpoint (missing)
- ❌ Token revocation (missing)

Dependencies:
- Database: PsyterDatabase
- Repository: IAuthRepository
- Stored Procedure: Organization_Authenticate_ByApplicationToken
- NuGet: System.IdentityModel.Tokens.Jwt

Integration Points:
- All protected endpoints require this token
- SharedAPIKey used for SecureHash validation

1.2 JWT Bearer Authentication¶

Implementation: AddAuthentication("Bearer")

Status: ✅ Fully Implemented

Features:
- ✅ JWT validation middleware
- ✅ Issuer validation
- ✅ Audience validation
- ✅ Lifetime validation
- ✅ Signature validation (HMAC-SHA256)
- ✅ Claims extraction (OrganizationId, SharedAPIKey)

Configuration:

{
  "Jwt": {
    "Key": "secret-key",
    "Issuer": "psyter.com",
    "Audience": "psyter_client"
  }
}

Dependencies:
- NuGet: Microsoft.AspNetCore.Authentication.JwtBearer

1.3 Authorization Policies¶

Status: ⚠️ Partially Implemented

Features:
- ✅ [Authorize] attribute on controllers
- ❌ Role-based authorization (missing)
- ❌ Policy-based authorization (missing)
- ❌ Organization-specific permissions (implicit only)

Current Limitation: All authenticated organizations have same permissions

Recommendation: Implement role-based access (e.g., ReadOnly, FullAccess)

2. User Management¶

2.1 User Registration¶

Endpoint: POST /api/user/register

Purpose: Register users under an organization

Status: ✅ Fully Implemented

Request:

{
  "referenceId": "ORG-USER-123",
  "name": "John Doe",
  "dob": "1990-05-15",
  "genderType": 1,
  "secureHash": "<hash>"
}

Features:
- ✅ Multi-tenant user creation
- ✅ Organization-specific user ID mapping (referenceId)
- ✅ Gender type support (Male/Female)
- ✅ Date of birth validation
- ✅ Secure hash validation
- ✅ Returns encrypted UserLoginInfoId
- ⚠️ Duplicate detection (unclear if implemented)

Dependencies:
- Database: PsyterDatabase
- Repository: IUserRepository.RegisterOrganizationUser()
- Action Filter: [ValidateSecureHash], [ValidateAntiXSS]

Validation Rules:
- Name: Required
- DOB: Required, valid date
- GenderType: Required (0=Female, 1=Male)
- ReferenceId: Required, unique per organization

2.2 User Validation¶

Internal Feature: Validates user belongs to organization

Status: ✅ Fully Implemented

Method: IUserRepository.ValidateOrganizationUserId(userId, orgId)

Used By:
- Session booking
- Care provider search (authenticated)
- Schedule viewing

Features:
- ✅ Multi-tenant ownership check
- ✅ Prevents cross-organization access
- ✅ Returns status indicator

2.3 Mental Health Assessment¶

Endpoints:
1. GET /api/user/getassessmentquestions
2. POST /api/user/submituserassessmentquestions

Status: ✅ Fully Implemented

Features:
- ✅ Screening question retrieval
- ✅ Assessment answer submission
- ✅ Support for multiple question types
- ✅ Validation of required answers

Question Types (inferred):
- Text answers (AnswerText)
- Multiple choice (CatScreeningQuetionOptionId)

Dependencies:
- Database: PsyterDatabase
- Repository: IUserRepository.GetScreeningQuestion(), SubmitUserAssessmentQuestions()

Use Case: Mental health screening for new patients

3. Care Provider Discovery¶

3.1 Provider Search with Filtering¶

Endpoint: POST /api/careprovider/getcareproviderslistwithschedule

Purpose: Search care providers with optional filters and availability

Status: ✅ Fully Implemented

Request:

{
  "userId": "<encrypted-or-empty>",
  "scheduleDate": "2025-11-15",
  "gmtTimeDiffrenceHours": 3,
  "applyFilter": true,
  "filterCriteriaObject": {
    "genderType": 0,
    "languageIds": [1, 2],
    "specialtyIds": [3, 5],
    "experienceLevel": 2,
    "serviceProviderLevel": 3,
    "minPrice": 100,
    "maxPrice": 500
  }
}

Features:
- ✅ Guest search (no userId)
- ✅ Authenticated search (with userId)
- ✅ Real-time availability integration
- ✅ Multi-criteria filtering
- ✅ Price range filtering
- ✅ Gender preference
- ✅ Language filtering (multi-select)
- ✅ Specialty filtering (multi-select)
- ✅ Experience level filtering
- ✅ Provider level filtering (Jr/Sr/Consultant)
- ✅ Multi-language support (PLang/SLang)

Response Data:

{
  "careProvidersList": [
    {
      "userLoginInfoId": "<encrypted>",
      "fullName": "Dr. Sarah Ahmed",
      "genderType": 0,
      "languagesList": [...],
      "specialtiesList": [...],
      "experienceYears": 10,
      "profileImageUrl": "...",
      "rating": 4.8,
      "availableScheduleHoursList": [...],
      "availableSlotsList": [...],
      "slotDurationType": {...}
    }
  ]
}

Advanced Features:
- ✅ Full name construction (PLang → SLang fallback)
- ✅ Schedule integration (hourly + slot-based)
- ✅ Timezone-aware scheduling
- ✅ Sort order from availability

Dependencies:
- Databases: PsyterDatabase, SchedulingDatabase
- Repositories: ICareProviderRepository, ISchedulingRepository
- Helper: SecurityHelper (for ID decryption)

3.2 Provider Schedule Details¶

Endpoint: POST /api/careprovider/getcareproviderschedule

Purpose: Get detailed schedule for specific provider

Status: ✅ Fully Implemented

Request:

{
  "careProviderId": "<encrypted>",
  "userId": "<encrypted>",
  "scheduleDate": "2025-11-15",
  "gmtTimeDiffrenceHours": 3
}

Features:
- ✅ Hourly availability
- ✅ Slot-based availability
- ✅ Slot duration settings
- ✅ Timezone conversion
- ✅ User-specific slot filtering (booked/available)

Dependencies:
- Database: SchedulingDatabase
- Repository: ISchedulingRepository.GetNextHourlyScheduleForCareProviders()

3.3 Provider Profile Data¶

Endpoint: POST /api/careprovider/getcareprovidersprofiledata

Purpose: Get full profile for care provider

Status: ✅ Fully Implemented

Features:
- ✅ Personal information
- ✅ Professional credentials
- ✅ Education history
- ✅ Certifications
- ✅ Bio (short/long)
- ✅ Languages spoken
- ✅ Specialties
- ✅ Ratings & reviews (if available)
- ✅ Profile images
- ✅ Session rates

Dependencies:
- Database: PsyterDatabase
- Repository: ICareProviderRepository.GetCareProvidersProfileData()

3.4 Filter Catalogue Data¶

Endpoint: GET /api/careprovider/getcataloguedataforfilters

Purpose: Get available filter options (metadata)

Status: ✅ Fully Implemented

Response:

{
  "languagesList": [
    { "id": 1, "namePLang": "English", "nameSLang": "الإنجليزية" },
    { "id": 2, "namePLang": "Arabic", "nameSLang": "العربية" }
  ],
  "specialtiesList": [...],
  "experienceLevelsList": [...],
  "providerLevelsList": [...]
}

Features:
- ✅ Multi-language catalogue
- ✅ Dynamic filter options
- ✅ Supports internationalization

Dependencies:
- Database: PsyterDatabase
- Repository: ICareProviderRepository.CatalogueDataForCareProvidersListFilters()

4. Scheduling & Availability¶

4.1 Hourly Schedule Retrieval¶

Internal Feature: Core scheduling functionality

Status: ✅ Fully Implemented

Method: ISchedulingRepository.GetNextHourlyScheduleForCareProviders()

Features:
- ✅ Multi-provider availability check
- ✅ Hourly granularity
- ✅ Timezone conversion
- ✅ Date filtering
- ✅ Consumer-specific filtering (booked slots)

Output:
- Available hours per provider
- Available slots (detailed)
- Slot duration settings
- Sort order for providers

4.2 Slot Validation¶

Internal Feature: Pre-booking slot verification

Status: ✅ Fully Implemented

Method: ISchedulingRepository.GetScheduleByHour()

Features:
- ✅ Real-time slot availability check
- ✅ Specific date/hour/provider validation
- ✅ Prevents double-booking
- ✅ Returns ScheduleId for booking

Used By: Session booking flow

4.3 Booking Status Management¶

Internal Feature: Track booking lifecycle

Status: ✅ Fully Implemented

Method: ISchedulingRepository.UpdateBookingStatus()

Booking Statuses:
| ID | Status | Description |
|----|--------|-------------|
| 1 | Confirmed | Successfully booked |
| 3 | Cancelled | User cancelled |
| 6 | Pending | Awaiting payment |
| 8 | Failed | Booking failed |

Features:
- ✅ Status transitions
- ✅ Timestamp tracking
- ✅ Authority tracking (who updated)
- ✅ Cancellation reason

5. Session Booking¶

5.1 Book Session¶

Endpoint: POST /api/sessionbooking/booksession

Purpose: Create therapy session booking

Status: ✅ Fully Implemented

Request:

{
  "userId": "<encrypted>",
  "careProviderId": "<encrypted>",
  "slotDate": "2025-11-15",
  "slotStartTime": "10:00:00",
  "slotEndTime": "11:00:00",
  "applicationMultiSlotId": "<encrypted>",
  "catCommunicationTypeId": 1,
  "isBookingFromMobile": false,
  "bookingPlatformId": 3,
  "referenceId": "ORG-USER-123",
  "name": "John Doe",
  "dob": "1990-05-15",
  "genderType": 1,
  "secureHash": "<hash>"
}

Features:
- ✅ Authenticated user booking
- ✅ Guest user auto-registration
- ✅ Slot availability validation
- ✅ Two-phase booking (Scheduling + Order)
- ✅ Video meeting auto-creation
- ✅ Push notification to provider
- ✅ Charity organization support (free bookings)
- ✅ Multi-platform tracking (mobile/web/API)
- ✅ Communication type selection (Video/Audio/Text)

Booking Flow:
1. User validation/registration
2. Setup booking data
3. Validate slot availability
4. Save scheduling booking → Get SlotBookingId
5. Save order record → Get OrderId
6. Create VideoSDK meeting → Get MeetingId
7. Update booking status (Confirmed/Failed)
8. Send FCM notification

Response:

{
  "status": 1,
  "data": {
    "meetingId": "abc-1234-efgh",
    "bookingId": "<encrypted>"
  }
}

Error Scenarios:
| Scenario | Response Reason | HTTP Code |
|----------|----------------|-----------|
| Missing parameters | EmptyParameter (1) | 400 |
| Invalid user | UserNotFound (18) | 400 |
| Slot not available | NotAllowed (16) | 404 |
| Slot already booked | RecordAlreadyExist (4) | 200 |
| Org balance out | CharityOrganizationBalanceOut (50) | 200 |

Dependencies:
- Databases: Both (PsyterDatabase, SchedulingDatabase)
- Repositories: Multiple (User, Scheduling, SessionBooking, Common)
- Helpers: SecurityHelper, VideoSDKHelper, FCMNotificationHelper, XmlHelper
- Action Filters: [ValidateSecureHash], [ValidateAntiXSS]

5.2 Cancel Booking¶

Endpoint: POST /api/sessionbooking/cancelbooking

Purpose: Cancel existing booking

Status: ✅ Fully Implemented

Request:

{
  "bookingId": "<encrypted>",
  "userId": "<encrypted>",
  "careProviderId": "<encrypted>",
  "secureHash": "<hash>"
}

Features:
- ✅ Ownership validation
- ✅ Refund processing (charity org balance)
- ✅ Booking status update (Cancelled)
- ✅ Prevents unauthorized cancellations
- ⚠️ No cancellation deadline enforcement (14-day rule mentioned but not enforced)

Cancellation Flow:
1. Validate booking ownership
2. Get booking details for refund
3. Process refund (restore charity org balance)
4. Update booking status to Cancelled (3)
5. Return confirmation

Refund Rules:
- Charity organization bookings: Restore balance
- Free bookings: No refund needed
- (Payment refunds: commented out in code)

Dependencies:
- Databases: Both
- Repositories: SessionBooking, Scheduling, User
- Helpers: SecurityHelper, XmlHelper

5.3 Booking Notifications¶

Internal Feature: Notify care provider of new bookings

Status: ✅ Fully Implemented

Method: SendBookingNotificationInternally()

Features:
- ✅ Dual-language notifications (English + Arabic)
- ✅ Platform-specific targeting (iOS/Android)
- ✅ Timezone-aware messaging
- ✅ Booking details in payload
- ✅ Reminder list integration

Notification Content:
- Client name (if available)
- Booking date/time (local timezone + UTC)
- Timezone information
- Meeting ID
- Notification type (NewBooking)

Topics:
- android_doctor_{providerId}~
- ios_doctor_{providerId}~

6. Video Conferencing Integration¶

6.1 VideoSDK Meeting Creation¶

Internal Feature: Auto-create video rooms for bookings

Status: ✅ Fully Implemented

Method: VideoSDKHelper.CreateAndSaveVideoSDKMeetingId()

Features:
- ✅ JWT token generation for VideoSDK API
- ✅ Meeting room creation
- ✅ Custom room ID support
- ✅ Auto-start recording (optional)
- ✅ Transcription with AI summary (optional)
- ✅ Grid layout configuration
- ✅ Database persistence

Configuration (from database):
- VIDEOSDK_API_ENDPOINT
- VIDEOSDK_API_KEY
- VIDEOSDK_SECRET_KEY
- VIDEO_SDK_ENABLE_RECORDING

Recording Features (when enabled):

{
  "autoStartConfig": {
    "recording": {
      "transcription": {
        "enabled": true,
        "summary": {
          "enabled": true,
          "prompt": "Psyter Online Therapy Session"
        }
      },
      "config": {
        "layout": {
          "type": "GRID",
          "priority": "SPEAKER",
          "gridSize": 2
        }
      }
    }
  }
}

6.2 Meeting Validation¶

Method: VideoSDKHelper.ValidateMeetingAsync()

Status: ✅ Implemented (not exposed via endpoint)

Purpose: Verify meeting exists and is valid

6.3 Session Recording Retrieval¶

Method: VideoSDKHelper.GetSessionRecording()

Status: ✅ Implemented (not exposed via endpoint)

Purpose: Get recording download links

Missing: Public endpoint to retrieve recordings

Recommendation: Add endpoint for care providers to access session recordings

7. Notifications¶

7.1 Firebase Cloud Messaging (FCM)¶

Implementation: FCMNotificationHelper

Status: ✅ Fully Implemented

Features:
- ✅ Topic-based messaging
- ✅ Platform-specific handling (iOS/Android)
- ✅ Data-only messages (Android)
- ✅ Notification + data messages (iOS)
- ✅ Multi-language support
- ✅ Custom payload templates

Supported Notification Types:
1. ProfileUpdate
2. NewBooking (actively used)
3. PayslipGenerated
4. HomeWorkAssigned
5. ReserveSlot
6. Referral
7. CancelRefundBooking
8. PsyterSupportNotification
9. SCHFSExpiry
10. RefundByAdmin
11. CommonNotification
12. ReminderNotification
13. OtherPartyJoined
14. ProviderSignedContract
15. NewMessage
16. AccountDeleted

Current Usage: Only NewBooking implemented in Tahoon API

7.2 Reminder Notifications¶

Method: ICommonRepository.GetUserRemindersList()

Status: ✅ Implemented (data retrieval only)

Purpose: Get reminder preferences for users

Missing: Scheduled notification sending (likely handled elsewhere)

8. Security Features¶

8.1 Secure Hash Validation¶

Implementation: ValidateSecureHashAttribute

Status: ✅ Fully Implemented

Features:
- ✅ HMAC-SHA256 signature verification
- ✅ Tamper detection
- ✅ Property-level inclusion control ([IncludeInHash])
- ✅ Alphabetical property sorting
- ✅ Shared API key as signing key

Applied To:
- User registration
- Session booking
- Session cancellation

8.2 Anti-XSS Protection¶

Implementation: ValidateAntiXSSAttribute, AntiXssAttribute

Status: ✅ Fully Implemented

Features:
- ✅ Pattern-based XSS detection
- ✅ Script tag blocking
- ✅ Event handler blocking
- ✅ Protocol-based attack prevention (javascript:, data:)
- ✅ Regex-based validation
- ⚠️ Allow HTML mode (permissive)

Applied To: All user input endpoints

8.3 ID Encryption/Decryption¶

Implementation: EncryptedModelBinder, SecurityHelper

Status: ✅ Fully Implemented

Features:
- ✅ Automatic ID decryption via model binding
- ✅ AES-256-CBC encryption
- ✅ Base64URL encoding
- ✅ Bidirectional encryption
- ✅ Long ID support

Encrypted Fields:
- UserId
- CareProviderId
- BookingId
- SlotAvailabilityId
- ApplicationMultiSlotId
- CareProviderSlotDurationId

8.4 Connection String Encryption¶

Implementation: BaseRepository.DecryptConnectionString()

Status: ✅ Fully Implemented

Features:
- ✅ Per-segment decryption
- ✅ Supports multiple connection strings
- ✅ AES-based decryption

Encrypted Segments:
- Data Source
- Initial Catalog
- User Id
- Password

8.5 Password Hashing¶

Implementation: SecurityHelper.GeneratePassword()

Status: ✅ Fully Implemented (not used in Tahoon API)

Algorithm: SHA-256

Use Case: Likely used by main Psyter API, not Tahoon

9. Configuration Management¶

9.1 Static Configuration¶

Source: appsettings.json

Status: ✅ Fully Implemented

Settings:
- Connection strings (encrypted)
- JWT configuration
- Security settings (AES keys, IV, salt, vector)
- AppBasePath (Swagger URL)
- CommandTimeout

9.2 Database Configuration¶

Source: CatAppConfigSetting table

Status: ✅ Fully Implemented

Method: ICommonRepository.GetAppConfigSettingsByGroupId()

Setting Groups:
- Smtp (1)
- Psyter (2)
- Ftp (4)
- SmartRoutingPayment (5)
- PsyterMediaAPI (11)
- TurnServerDetail (14)
- FailedTransactionIntimationUsers (16)
- SMSGatewaySettings (18)
- GoogleLoginSettings (19)
- GoogleReCaptchaSettings (20)
- DeleteUserAccountSettings (22)
- VideoSDK (25) ← Used in Tahoon API

Dynamic Loading: VideoSDKHelper loads config from DB at runtime

10. Feature Completeness Matrix¶

11. Missing Features¶

11.1 Token Refresh¶

Priority: High
Description: No endpoint to refresh expired tokens
Impact: Clients must re-authenticate every 24 hours
Recommendation: Implement /api/auth/refresh endpoint

11.2 Token Revocation¶

Priority: Medium
Description: No way to invalidate tokens before expiry
Impact: Security risk if token compromised
Recommendation: Implement token blacklist or short-lived tokens with refresh

11.3 Session Recording Access¶

Priority: Medium
Description: VideoSDK recording retrieval implemented but not exposed
Impact: Providers cannot access session recordings via API
Recommendation: Add endpoint: GET /api/sessionbooking/getrecording/{bookingId}

11.4 Booking History¶

Priority: Medium
Description: No endpoint to retrieve user’s booking history
Impact: Clients must track bookings externally
Recommendation: Add endpoint: GET /api/user/bookings

11.5 Provider Availability Update¶

Priority: Low (handled by main Psyter API)
Description: No endpoint for organizations to update provider availability
Impact: Organizations cannot manage availability
Recommendation: Consider if needed for B2B use cases

11.6 Webhook Notifications¶

Priority: Medium
Description: No webhook support for async notifications
Impact: Clients must poll for updates
Recommendation: Implement webhooks for booking status changes

11.7 Rate Limiting¶

Priority: High
Description: No API rate limiting implemented
Impact: Potential abuse, DDoS risk
Recommendation: Implement rate limiting (e.g., 100 req/min per org)

11.8 API Versioning¶

Priority: Medium
Description: No explicit API versioning
Impact: Breaking changes difficult to manage
Recommendation: Implement URL-based versioning (/api/v1/...)

11.9 Pagination¶

Priority: Medium
Description: Provider search returns all results (no pagination)
Impact: Performance issues with large datasets
Recommendation: Add pagination parameters (page, pageSize)

11.10 Audit Logging¶

Priority: High
Description: No audit trail for sensitive operations
Impact: Compliance issues, hard to troubleshoot
Recommendation: Log all booking operations, user registrations

12. Integration Dependencies¶

12.1 External Services¶

12.2 Internal Dependencies¶

12.3 Database Stored Procedures (Critical)¶

Risk: Tight coupling to database schema

13. Feature Usage Patterns¶

13.1 Typical Integration Flow¶

1. Organization Setup
   └─► Receive ApplicationToken from Psyter

2. Authentication
   └─► POST /api/auth/token (get JWT)

3. User Registration
   └─► POST /api/user/register (create user)
   └─► POST /api/user/submituserassessmentquestions (if needed)

4. Provider Discovery
   └─► GET /api/careprovider/getcataloguedataforfilters
   └─► POST /api/careprovider/getcareproviderslistwithschedule

5. Session Booking
   └─► POST /api/sessionbooking/booksession
   └─► [User receives meetingId for video session]

6. (Optional) Cancellation
   └─► POST /api/sessionbooking/cancelbooking

13.2 Guest User Flow¶

1. Get Token (organization-level)
2. Search Providers (no userId)
3. Book Session
   └─► Auto-register user (provide referenceId, name, DOB)
   └─► Booking created
   └─► Return encrypted userId for future use

14. Feature Recommendations¶

14.1 Do Now (Critical)¶

1. ✅ Implement API rate limiting
2. ✅ Add audit logging for bookings
3. ✅ Implement token refresh endpoint
4. ✅ Add pagination to provider search
5. ✅ Document all API endpoints (OpenAPI spec)

14.2 Do Next (Important)¶

1. ⚠️ Add booking history endpoint
2. ⚠️ Expose recording retrieval endpoint
3. ⚠️ Implement webhook notifications
4. ⚠️ Add API versioning (v1)
5. ⚠️ Implement role-based authorization

14.3 Plan (Nice to Have)¶

1. 📋 Add bulk booking endpoint
2. 📋 Provider favorites/bookmarks
3. 📋 Session rescheduling
4. 📋 Payment integration (if needed)
5. 📋 Multi-language API responses

Conclusion¶

The Tahoon API provides a comprehensive B2B integration layer with all essential features for external organizations to book therapy sessions. The feature set is well-balanced between security, usability, and performance.

Strengths:
- Complete booking lifecycle
- Strong security features
- Real-time availability
- Multi-tenant architecture
- Video conferencing integration

Gaps:
- No token refresh mechanism
- Missing audit trail
- No rate limiting
- Limited documentation
- No pagination

Overall Maturity: Production-Ready with recommended improvements for scalability and security.