openapi.yaml

openapi: 3.1.0
info:
  title: Biensperience API
  description: |
    # Biensperience Travel Experience Platform API

    Biensperience is a visual travel experience platform that enables users to plan experiences and share their plans with other users who can plan similar experiences. Users can create detailed travel plans with checklists, photos, and hierarchical plan items, then share these experiences to inspire and guide others in planning their own adventures.

    ## Authentication

    The API supports multiple authentication methods:

    ### JWT Authentication
    Most endpoints require JWT authentication via the `Authorization` header:
    ```
    Authorization: Bearer <jwt_token>
    ```

    ### OAuth Authentication
    Social login via Facebook, Google, and Twitter is supported through dedicated OAuth endpoints.

    ### API Tokens
    For programmatic access, API tokens can be used instead of JWT tokens.

    ## Rate Limiting

    The API implements comprehensive rate limiting:
    - **Authentication endpoints**: 5 requests per 15 minutes
    - **API endpoints**: 1000 requests per 15 minutes (configurable)
    - **Modification endpoints**: 100 requests per 15 minutes
    - **Collaborator management**: 50 requests per 15 minutes
    - **AI endpoints**: 100 requests per 15 minutes
    - **BienBot endpoints**: 30 requests per 15 minutes (super admins exempt)

    ## Feature Flags

    Certain features require feature flags to be enabled on the user account:

    | Flag | Description |
    |------|-------------|
    | `ai_features` | Access to AI-powered features (autocomplete, improve, translate, summarize, generate tips) |
    | `beta_ui` | Access to beta UI features |
    | `advanced_analytics` | Access to advanced analytics features |
    | `real_time_collaboration` | Real-time collaboration via WebSocket |
    | `document_ai_parsing` | AI-powered document parsing and extraction |
    | `bulk_export` | Bulk export of plans and experiences |
    | `curator` | Curator designation for creating curated experiences with bio and links |
    | `chat` | In-app messaging (provider-agnostic) |
    | `bienbot` | BienBot AI assistant (alias for ai_features in some contexts) |

    Requests to feature-gated endpoints without the required flag return 403 Forbidden.
    Super admins bypass all feature flag requirements.

    ## Permissions Framework

    Resources implement a role-based permissions system:

    ### Permission Roles
    - **Owner**: Full control over resource (edit, delete, manage permissions)
    - **Collaborator**: Can edit content but cannot manage permissions or delete
    - **Contributor**: Can view and create derivative works (fork/clone)

    ### Permission Inheritance
    Resources can inherit permissions from related resources with a maximum depth of 3 levels.

    ## Error Responses

    All API errors follow a consistent format:
    ```json
    {
      "success": false,
      "error": "Error message",
      "details": {
        "field": "validation error details"
      }
    }
    ```

    Common HTTP status codes:
    - `200`: Success
    - `201`: Created
    - `400`: Bad Request
    - `401`: Unauthorized
    - `403`: Forbidden
    - `404`: Not Found
    - `409`: Conflict
    - `422`: Validation Error
    - `429`: Too Many Requests
    - `500`: Internal Server Error

    ## File Upload

    The API supports file uploads for photos and documents:

    ### Photo Upload
    - **Formats**: JPEG, PNG, WebP
    - **Max size**: 10MB per file
    - **Storage**: AWS S3 with automatic optimization

    ### Document Upload
    - **Formats**: PDF, DOC, DOCX, TXT
    - **Max size**: 25MB per file
    - **Storage**: Protected S3 bucket for sensitive documents

    ## WebSocket Support

    Real-time features are available via WebSocket when enabled:
    - Live collaboration on plans
    - Real-time notifications
    - Activity feed updates

    ## Data Models

    ### User
    Represents authenticated users with profile information, preferences, and social accounts.

    ### Destination
    Travel locations with fuzzy matching for duplicates and collaborative permissions.

    ### Experience
    Core travel experiences with hierarchical plan items, photos, and sharing capabilities.

    ### Plan
    User-specific instances of experiences with completion tracking and collaboration features.

    ### Photo
    Image assets with permission-based visibility control and AWS S3 storage.

    ### Document
    Uploaded documents with secure storage and access controls.
  version: 0.6.4
  contact:
    name: Biensperience Support
    url: https://github.com/gokepelemo/biensperience
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3001/api
    description: Development server
  - url: https://api.biensperience.com/api
    description: Production server

security:
  - bearerAuth: []
  - apiTokenAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or OAuth flow
    apiTokenAuth:
      type: apiKey
      in: header
      name: X-API-Token
      description: API token for programmatic access

  schemas:
    PhotoEntry:
      type: object
      description: A photo entry with default flag in the photos array
      properties:
        photo:
          type: string
          description: Photo ID or populated Photo object
        default:
          type: boolean
          description: Whether this is the default/cover photo
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
      required:
        - success
        - error

    Success:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          description: Response data
        message:
          type: string
          description: Success message
      required:
        - success

    User:
      type: object
      properties:
        _id:
          type: string
          description: User ID
        name:
          type: string
          description: Full name
        email:
          type: string
          format: email
          description: Email address
        provider:
          type: string
          enum: [local, facebook, google, twitter]
          description: Authentication provider
        photos:
          type: array
          items:
            $ref: '#/components/schemas/PhotoEntry'
          description: Array of photo entries with default flag
        isSuperAdmin:
          type: boolean
          description: Super admin status
        role:
          type: string
          enum: [super_admin, regular_user]
          description: User role
        emailConfirmed:
          type: boolean
          description: Email verification status
        visibility:
          type: string
          enum: [private, public]
          description: Profile visibility
        preferences:
          type: object
          properties:
            theme:
              type: string
              enum: [light, dark, system-default]
            currency:
              type: string
            language:
              type: string
            timezone:
              type: string
            profileVisibility:
              type: string
              enum: [private, public]
            notifications:
              type: object
              properties:
                enabled:
                  type: boolean
                channels:
                  type: array
                  items:
                    type: string
                    enum: [email, push, sms, bienbot, webhook]
                types:
                  type: array
                  items:
                    type: string
                    enum: [activity, reminder, marketing, updates]
        location:
          type: object
          properties:
            displayName:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            countryCode:
              type: string
            postalCode:
              type: string
            coordinates:
              type: object
              properties:
                type:
                  type: string
                  enum: [Point]
                coordinates:
                  type: array
                  items:
                    type: number
                  minItems: 2
                  maxItems: 2
                  description: "[longitude, latitude]"
        feature_flags:
          type: array
          items:
            $ref: '#/components/schemas/FeatureFlag'
          description: Feature flags controlling access to platform features
        bio:
          type: string
          maxLength: 500
          description: Curator bio/about text (requires curator feature flag)
        links:
          type: array
          items:
            $ref: '#/components/schemas/UserLink'
          description: Curator external links (requires curator feature flag)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - name
        - email

    Destination:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        country:
          type: string
        state:
          type: string
        overview:
          type: string
        map_location:
          type: string
          description: Legacy string location field (deprecated, use location)
        location:
          $ref: '#/components/schemas/Location'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/PhotoEntry'
        travel_tips:
          type: array
          items:
            oneOf:
              - type: string
              - type: object
                properties:
                  type:
                    type: string
                  value:
                    type: string
                required:
                  - type
                  - value
        visibility:
          type: string
          enum: [private, contributors, public]
          default: public
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        users_favorite:
          type: array
          items:
            type: string
          description: Array of User IDs who favorited this destination
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - name
        - country

    Experience:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        overview:
          type: string
        destination:
          $ref: '#/components/schemas/Destination'
        experience_type:
          type: array
          items:
            type: string
        plan_items:
          type: array
          items:
            $ref: '#/components/schemas/PlanItem'
        photos:
          type: array
          items:
            $ref: '#/components/schemas/PhotoEntry'
        visibility:
          type: string
          enum: [private, contributors, public]
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        difficulty:
          type: number
          minimum: 1
          maximum: 10
        rating:
          type: number
          minimum: 0
          maximum: 5
        cost_estimate:
          type: number
          description: Virtual property - total estimated cost
        max_planning_days:
          type: number
          description: Virtual property - maximum planning days
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - name
        - destination

    PlanItem:
      type: object
      properties:
        _id:
          type: string
        text:
          type: string
        photo:
          type: string
        url:
          type: string
        cost_estimate:
          type: number
        planning_days:
          type: number
        parent:
          type: string
          description: Parent plan item ID for hierarchy
        activity_type:
          type: string
          enum: [accommodation, transport, food, drinks, coffee, sightseeing, museum, nature, adventure, sports, entertainment, wellness, tour, class, nightlife, religious, local, shopping, market, health, banking, communication, admin, laundry, rental, photography, meeting, work, rest, packing, checkpoint, custom, null]
        location:
          $ref: '#/components/schemas/Location'
      required:
        - text

    Plan:
      type: object
      properties:
        _id:
          type: string
        experience:
          $ref: '#/components/schemas/Experience'
        user:
          $ref: '#/components/schemas/User'
        planned_date:
          type: string
          format: date
        plan:
          type: array
          items:
            $ref: '#/components/schemas/PlanItemSnapshot'
        costs:
          type: array
          items:
            $ref: '#/components/schemas/Cost'
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        notes:
          type: string
        currency:
          type: string
          default: USD
          description: Currency code for all costs in this plan
        pinnedItemId:
          type: string
          description: Plan item ID pinned to the top of the plan
        accessRequests:
          type: array
          description: Pending access requests from users
          items:
            type: object
            properties:
              user:
                type: string
                description: User ID requesting access
              requestedAt:
                type: string
                format: date-time
              message:
                type: string
        total_cost:
          type: number
          description: Virtual property - total cost
        max_planning_days:
          type: number
          description: Virtual property - maximum planning days
        completion_percentage:
          type: number
          description: Virtual property - completion percentage
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - experience
        - user

    PlanItemSnapshot:
      type: object
      properties:
        _id:
          type: string
        plan_item_id:
          type: string
        complete:
          type: boolean
        cost:
          type: number
        planning_days:
          type: number
        text:
          type: string
        url:
          type: string
        photos:
          type: array
          items:
            type: string
          description: Photo IDs (snapshot)
        parent:
          type: string
        activity_type:
          type: string
          enum: [accommodation, transport, food, drinks, coffee, sightseeing, museum, nature, adventure, sports, entertainment, wellness, tour, class, nightlife, religious, local, shopping, market, health, banking, communication, admin, laundry, rental, photography, meeting, work, rest, packing, checkpoint, custom, null]
        scheduled_date:
          type: string
          format: date
        scheduled_time:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        details:
          type: object
          properties:
            notes:
              type: array
              items:
                $ref: '#/components/schemas/Note'
            photos:
              type: array
              items:
                type: string
            documents:
              type: array
              items:
                $ref: '#/components/schemas/DocumentReference'
            transport:
              $ref: '#/components/schemas/TransportExtension'
            parking:
              $ref: '#/components/schemas/ParkingExtension'
            discount:
              $ref: '#/components/schemas/DiscountExtension'
        assignedTo:
          type: string
          description: User ID of assigned collaborator
      required:
        - plan_item_id

    Permission:
      type: object
      properties:
        _id:
          type: string
          description: User or resource ID
        entity:
          type: string
          enum: [user, destination, experience]
        type:
          type: string
          enum: [owner, collaborator, contributor]
        granted_at:
          type: string
          format: date-time
        granted_by:
          type: string
          description: User ID who granted permission
      required:
        - _id
        - entity
        - type

    Location:
      type: object
      properties:
        address:
          type: string
        geo:
          type: object
          properties:
            type:
              type: string
              enum: [Point]
            coordinates:
              type: array
              items:
                type: number
              minItems: 2
              maxItems: 2
              description: "[longitude, latitude]"
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string
        placeId:
          type: string
      required:
        - address

    Cost:
      type: object
      properties:
        _id:
          type: string
        title:
          type: string
        description:
          type: string
        cost:
          type: number
        currency:
          type: string
          default: USD
        category:
          type: string
          enum: [accommodation, transport, food, activities, equipment, other, null]
          description: Cost category for grouping and reporting
        date:
          type: string
          format: date-time
          description: Date when the cost was incurred
        plan_item:
          type: string
          description: Linked plan item ID
        collaborator:
          type: string
          description: User ID who paid or is responsible
        created_at:
          type: string
          format: date-time
      required:
        - title
        - cost

    Note:
      type: object
      properties:
        _id:
          type: string
        user:
          type: string
          description: User ID who created the note
        content:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - user
        - content

    DocumentReference:
      type: object
      properties:
        document:
          type: string
          description: Document ID
        addedBy:
          type: string
          description: User ID who added the document
        addedAt:
          type: string
          format: date-time
        displayName:
          type: string
        contextNotes:
          type: string
      required:
        - document

    TransportExtension:
      type: object
      properties:
        mode:
          type: string
          enum: [flight, train, cruise, ferry, bus, coach, car_share, ride, metro, local_transit, bike_rental, scooter]
        vendor:
          type: string
        trackingNumber:
          type: string
        country:
          type: string
        departureTime:
          type: string
          format: date-time
        arrivalTime:
          type: string
          format: date-time
        departureLocation:
          type: string
        arrivalLocation:
          type: string
        status:
          type: string
          enum: [scheduled, active, completed, cancelled, delayed]
        transportNotes:
          type: string
        flight:
          type: object
          properties:
            terminal:
              type: string
            arrivalTerminal:
              type: string
            gate:
              type: string
            arrivalGate:
              type: string
        train:
          type: object
          properties:
            carriageNumber:
              type: string
            platform:
              type: string
            arrivalPlatform:
              type: string
        cruise:
          type: object
          properties:
            deck:
              type: string
            shipName:
              type: string
            embarkationPort:
              type: string
            disembarkationPort:
              type: string
        bus:
          type: object
          properties:
            stopName:
              type: string
            arrivalStopName:
              type: string
        carShare:
          type: object
          properties:
            vehicleModel:
              type: string
            vehicleColor:
              type: string
            licensePlate:
              type: string
            pickupSpot:
              type: string
        metro:
          type: object
          properties:
            lineNumber:
              type: string
            direction:
              type: string
            platform:
              type: string
      required:
        - mode

    ParkingExtension:
      type: object
      properties:
        parkingType:
          type: string
          enum: [street, garage, lot, valet, hotel, airport, venue, private, other]
        facilityName:
          type: string
        address:
          type: string
        spotNumber:
          type: string
        level:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        cost:
          type: number
        currency:
          type: string
        prepaid:
          type: boolean
        confirmationNumber:
          type: string
        accessCode:
          type: string
        status:
          type: string
          enum: [reserved, active, completed, cancelled]
        parkingNotes:
          type: string
      required:
        - parkingType

    DiscountExtension:
      type: object
      properties:
        discountType:
          type: string
          enum: [promo_code, coupon, loyalty, member, early_bird, group, seasonal, referral, other]
        code:
          type: string
        description:
          type: string
        discountValue:
          type: number
        isPercentage:
          type: boolean
        currency:
          type: string
        minimumPurchase:
          type: number
        maxDiscount:
          type: number
        expiresAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [active, applied, expired, invalid]
        source:
          type: string
        discountNotes:
          type: string
      required:
        - discountType

    Photo:
      type: object
      properties:
        _id:
          type: string
        url:
          type: string
          description: Public URL to access the photo
        s3_key:
          type: string
          description: AWS S3 object key
        photo_credit:
          type: string
          description: Attribution/credit for the photo
        photo_credit_url:
          type: string
          description: URL for the photo credit link
        caption:
          type: string
          description: Photo caption/description
        width:
          type: number
          description: Photo width in pixels
        height:
          type: number
          description: Photo height in pixels
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - url

    Activity:
      type: object
      properties:
        _id:
          type: string
        timestamp:
          type: string
          format: date-time
        action:
          type: string
          enum:
            - resource_created
            - resource_updated
            - resource_deleted
            - permission_added
            - permission_removed
            - collaborator_added
            - collaborator_removed
            - plan_created
            - plan_updated
            - plan_deleted
            - plan_item_completed
            - plan_item_uncompleted
            - plan_item_photo_added
            - plan_item_visibility_changed
            - plan_item_note_added
            - plan_item_note_updated
            - plan_item_note_deleted
            - cost_added
            - cost_updated
            - cost_deleted
            - follow_created
            - follow_removed
            - favorite_added
            - favorite_removed
            - experience_planned
        actor:
          type: object
          properties:
            _id:
              type: string
            email:
              type: string
            name:
              type: string
            role:
              type: string
        resource:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
              enum: [User, Destination, Experience, Plan, Photo, Document, PlanItem]
            name:
              type: string
        target:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
            name:
              type: string
        previousState:
          type: object
        newState:
          type: object
        reason:
          type: string
        metadata:
          type: object
        parentActivityId:
          type: string
          nullable: true
          description: Groups multi-step flows; child activities are hidden from feeds
        tags:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [success, failure, partial]
      required:
        - timestamp
        - action
        - actor
        - resource

    AccessRequest:
      type: object
      properties:
        _id:
          type: string
          description: Access request ID
        requester:
          oneOf:
            - type: string
            - type: object
              properties:
                _id:
                  type: string
                name:
                  type: string
                email:
                  type: string
          description: Requester user ID or populated user object
        message:
          type: string
          description: Optional message from the requester
        status:
          type: string
          enum: [pending, approved, declined]
        respondedAt:
          type: string
          format: date-time
          description: When the request was responded to
        respondedBy:
          type: string
          description: User ID of who responded
        createdAt:
          type: string
          format: date-time

    ChatChannel:
      type: object
      description: Chat channel information returned by channel creation endpoints
      properties:
        type:
          type: string
          example: messaging
          description: Stream Chat channel type
        id:
          type: string
          description: Channel ID (deterministic based on context)
          examples:
            - dm_user1_user2
            - plan_abc123
            - planItem_abc123_def456
        members:
          type: array
          items:
            type: string
          description: User IDs of channel members

    EnrichedActivityFeedItem:
      type: object
      description: Enriched activity item returned by dashboard and follow feed endpoints
      properties:
        id:
          type: string
          description: Activity ID
        action:
          type: string
          description: Human-readable action text (e.g., "Created", "Planned")
        actionType:
          type: string
          description: Raw action type for client-side filtering (e.g., "plan_created")
        item:
          type: string
          nullable: true
          description: Display name of the primary resource
        targetItem:
          type: string
          nullable: true
          description: Display name of the target (e.g., plan item name for completions)
        link:
          type: string
          nullable: true
          description: Deep link to the resource (may include hash fragments)
        time:
          type: string
          description: Relative time string (e.g., "2 hours ago")
        timestamp:
          type: string
          format: date-time
          description: ISO timestamp of the activity
        resourceType:
          type: string
          description: Resource type (Experience, Plan, Destination, User)
        actorId:
          type: string
          description: ID of the user who performed the action
        targetId:
          type: string
          nullable: true
          description: ID of the target entity
        actorName:
          type: string
          nullable: true
          description: Name of the user who performed the action
        actorPhoto:
          type: string
          nullable: true
          description: URL of the actor's profile photo for avatar display
        targetName:
          type: string
          nullable: true
          description: Name of the target entity
        photoId:
          type: string
          nullable: true
          description: Photo ID for plan_item_photo_added activities (for thumbnail display)
      required:
        - id
        - action
        - actionType
        - time
        - timestamp

    Document:
      type: object
      properties:
        _id:
          type: string
        user:
          type: string
          description: Document owner ID
        entityType:
          type: string
          enum: [plan, plan_item, experience, destination]
        entityId:
          type: string
        planId:
          type: string
        planItemId:
          type: string
        originalFilename:
          type: string
        mimeType:
          type: string
        fileSize:
          type: integer
        documentType:
          type: string
          enum: [pdf, image, word, text]
        s3Key:
          type: string
        s3Url:
          type: string
        s3Bucket:
          type: string
        isProtected:
          type: boolean
        bucketType:
          type: string
          enum: [public, protected]
        status:
          type: string
          enum: [pending, processing, completed, failed, reprocessing]
        extractedText:
          type: string
        processingResult:
          type: object
          properties:
            method:
              type: string
              enum: [tesseract-ocr, llm-vision, pdf-parse, mammoth, direct-read, placeholder, failed]
            confidence:
              type: number
            characterCount:
              type: integer
            pageCount:
              type: integer
            language:
              type: string
            processedAt:
              type: string
              format: date-time
        aiParsedData:
          type: object
          properties:
            documentType:
              type: string
              enum: [flight, hotel, activity, restaurant, transport, receipt, itinerary, other]
            summary:
              type: string
            confirmationNumber:
              type: string
            totalCost:
              type: number
            currency:
              type: string
        aiParsingEnabled:
          type: boolean
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        metadata:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
              type:
                type: string
        lastProcessedAt:
          type: string
          format: date-time
        processAttempts:
          type: integer
        maxProcessAttempts:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - _id
        - user
        - entityType
        - entityId
        - originalFilename
        - mimeType
        - fileSize
        - documentType
        - s3Key
        - s3Url
        - s3Bucket

    DocumentResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Document'
        message:
          type: string

    SearchResult:
      type: object
      properties:
        destinations:
          type: array
          items:
            $ref: '#/components/schemas/Destination'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/Experience'
        plans:
          type: array
          items:
            $ref: '#/components/schemas/Plan'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
        total:
          type: number

    Dashboard:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        stats:
          type: object
          properties:
            totalExperiences:
              type: number
            totalPlans:
              type: number
            completedPlans:
              type: number
            upcomingPlans:
              type: number
        recentActivity:
          type: array
          items:
            $ref: '#/components/schemas/Activity'
        upcomingPlans:
          type: array
          items:
            $ref: '#/components/schemas/Plan'

    Invite:
      type: object
      description: Invite code for granting access to experiences or destinations
      properties:
        _id:
          type: string
        code:
          type: string
          description: Unique invite code string
        createdBy:
          type: string
          description: User ID who created the invite
        email:
          type: string
          format: email
          description: Optional email address the invite is intended for
        inviteeName:
          type: string
          description: Optional name for the invitee
        experiences:
          type: array
          items:
            type: string
          description: Experience IDs this invite grants access to
        destinations:
          type: array
          items:
            type: string
          description: Destination IDs this invite grants access to
        maxUses:
          type: number
          default: 1
          description: Maximum number of times this invite can be used
        usedCount:
          type: number
          default: 0
          description: Number of times this invite has been redeemed
        redeemedBy:
          type: array
          items:
            type: string
          description: User IDs who have redeemed this invite
        expiresAt:
          type: string
          format: date-time
        isActive:
          type: boolean
          default: true
        customMessage:
          type: string
          description: Optional message to include with the invite
        permissionType:
          type: string
          enum: [collaborator, contributor]
          default: collaborator
        mutualFollow:
          type: boolean
          default: false
          description: Whether accepting the invite creates a mutual follow
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - code
        - createdBy

    Token:
      type: object
      description: API token for programmatic access
      properties:
        _id:
          type: string
        user:
          type: string
          description: User ID who owns this token
        tokenHash:
          type: string
          description: Hashed token value (only the hash is stored, never the raw token)
        tokenPrefix:
          type: string
          description: First 8 characters of the token for display/identification purposes
        name:
          type: string
          description: User-provided name for this token
          default: API Token
        lastUsed:
          type: string
          format: date-time
          description: Last time this token was used
        expiresAt:
          type: string
          format: date-time
          description: Expiration date (null means never expires)
        isActive:
          type: boolean
          default: true
          description: Whether the token is active (false = revoked)
        createdFrom:
          type: string
          description: IP address where the token was created
        createdUserAgent:
          type: string
          description: User agent string from token creation
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - user
        - tokenHash
        - tokenPrefix

    FeatureFlag:
      type: object
      description: Feature flag controlling access to platform features
      properties:
        flag:
          type: string
          description: Unique feature flag identifier
          enum: [ai_features, beta_ui, advanced_analytics, real_time_collaboration, document_ai_parsing, bulk_export, curator, chat, bienbot]
        enabled:
          type: boolean
          default: true
          description: Whether the flag is enabled
        config:
          type: object
          description: Optional JSON configuration for the flag
        granted_at:
          type: string
          format: date-time
          description: When the flag was granted
        granted_by:
          type: string
          description: User ID who granted the flag
        expires_at:
          type: string
          format: date-time
          description: Optional expiration date (null = never expires)
        reason:
          type: string
          description: Optional reason for granting the flag
      required:
        - flag

    UserLink:
      type: object
      description: External link for curator profiles
      properties:
        type:
          type: string
          enum: [twitter, instagram, facebook, youtube, tiktok, linkedin, pinterest, github, website, custom]
          default: custom
          description: Link type (social network or custom)
        username:
          type: string
          description: Username for social networks (without URL prefix)
        title:
          type: string
          maxLength: 100
          description: Display title for the link
        url:
          type: string
          format: uri
          description: Full URL
        meta:
          type: object
          description: Optional metadata
      required:
        - title
        - url

    AICompletionRequest:
      type: object
      description: Request for AI text completion
      properties:
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum: [system, user, assistant]
              content:
                type: string
            required:
              - role
              - content
        task:
          type: string
          enum: [autocomplete, improve, translate, summarize, general]
          default: general
        options:
          type: object
          properties:
            provider:
              type: string
              enum: [openai, anthropic, mistral, gemini]
            model:
              type: string
            temperature:
              type: number
              minimum: 0
              maximum: 1
            maxTokens:
              type: integer
              minimum: 1
              maximum: 4096
      required:
        - messages

    AICompletionResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            content:
              type: string
              description: Generated text content
            usage:
              type: object
              properties:
                inputTokens:
                  type: integer
                outputTokens:
                  type: integer
                totalTokens:
                  type: integer
            model:
              type: string
              description: Model used for completion
            provider:
              type: string
              description: AI provider used

    AIStatusResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            available:
              type: boolean
              description: Whether AI features are available
            defaultProvider:
              type: string
              description: Default AI provider
            providers:
              type: object
              description: Map of provider name to configured status
              additionalProperties:
                type: boolean

    BienBotSession:
      type: object
      description: BienBot AI assistant conversation session
      properties:
        _id:
          type: string
          description: Session ID
        user:
          type: string
          description: User ID (session owner)
        title:
          type: string
          description: Auto-generated from first user message (max 80 chars)
        invoke_context:
          type: object
          description: Entity page where BienBot was opened (set at session creation)
          properties:
            entity:
              type: string
              enum: [destination, experience, plan, plan_item, user]
              nullable: true
            entity_id:
              type: string
              nullable: true
            entity_label:
              type: string
              description: Resolved from DB (never trusts client)
              nullable: true
        context:
          type: object
          description: Accumulated entity IDs as conversation progresses
          properties:
            destination_id:
              type: string
              nullable: true
            experience_id:
              type: string
              nullable: true
            plan_id:
              type: string
              nullable: true
            plan_item_id:
              type: string
              nullable: true
        messages:
          type: array
          description: Multi-turn conversation history
          items:
            $ref: '#/components/schemas/BienBotMessage'
        summary:
          type: object
          description: Cached resume summary (6-hour TTL)
          properties:
            text:
              type: string
              nullable: true
            suggested_next_steps:
              type: array
              items:
                type: string
            generated_at:
              type: string
              format: date-time
              nullable: true
        pending_actions:
          type: array
          description: Proposed actions awaiting user confirmation
          items:
            $ref: '#/components/schemas/BienBotPendingAction'
        status:
          type: string
          enum: [active, archived]
          default: active
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - user
        - status

    BienBotMessage:
      type: object
      description: A single conversation turn in a BienBot session
      properties:
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
        timestamp:
          type: string
          format: date-time
        intent:
          type: string
          nullable: true
          description: Intent classification from the classifier
        actions_taken:
          type: array
          items:
            type: string
          description: Action types executed in this turn
        message_type:
          type: string
          enum: [shared_comment]
          nullable: true
          description: |
            Set to `shared_comment` for peer-exchange messages (not forwarded to the LLM).
            These are sent either by a non-owner collaborator or by the session owner using
            the `/message` slash command, and by owners replying directly to a collaborator message.
        sent_by:
          type: string
          nullable: true
          description: |
            ObjectId of the user who sent this message. Present on `user`-role messages in shared
            sessions and on optimistic `shared_comment` messages so the UI can distinguish the
            current user's own messages from collaborator messages before the server response arrives.
        msg_id:
          type: string
          nullable: true
          description: |
            Stable message identifier used for reply threading. Present on persisted messages;
            absent on optimistic placeholders.
        reply_to:
          type: string
          nullable: true
          description: msg_id of the message this is a reply to (shared_comment replies only)
        sender_name:
          type: string
          nullable: true
          description: Display name of the sender (populated for collaborator shared_comment messages)
      required:
        - role
        - content

    BienBotPendingAction:
      type: object
      description: A proposed action awaiting user confirmation
      properties:
        id:
          type: string
          description: Unique action ID (action_<8_random_chars>)
        type:
          type: string
          enum:
            - create_destination
            - update_destination
            - toggle_favorite_destination
            - create_experience
            - update_experience
            - add_experience_plan_item
            - update_experience_plan_item
            - delete_experience_plan_item
            - create_plan
            - update_plan
            - delete_plan
            - add_plan_items
            - update_plan_item
            - delete_plan_item
            - add_plan_item_note
            - add_plan_item_detail
            - assign_plan_item
            - unassign_plan_item
            - add_plan_cost
            - update_plan_cost
            - delete_plan_cost
            - invite_collaborator
            - remove_collaborator
            - sync_plan
            - set_member_location
            - remove_member_location
            - workflow
          description: |
            One of the 27 allowed action types. `workflow` is a meta-type that
            composes multiple steps with `$step_N.field` dependency references.
        payload:
          type: object
          description: Action-specific parameters. For `workflow`, contains a `steps` array.
        description:
          type: string
          description: Human-readable description shown in the confirmation UI
        executed:
          type: boolean
          default: false
        result:
          type: object
          nullable: true
          description: Result of execution (populated after execution)
      required:
        - id
        - type
        - payload
        - description

    BienBotChatRequest:
      type: object
      description: Request body for the BienBot chat endpoint
      properties:
        message:
          type: string
          maxLength: 8000
          description: User message text
        sessionId:
          type: string
          nullable: true
          description: Existing session ID, or omit to create a new session
        invokeContext:
          type: object
          nullable: true
          description: Entity context (only sent on first message when sessionId is null)
          properties:
            entity:
              type: string
              enum: [destination, experience, plan, plan_item, user]
            id:
              type: string
              description: Entity ID
            label:
              type: string
              description: Display label (resolved server-side, client value ignored)
          required:
            - entity
            - id
      required:
        - message

    BienBotExecuteRequest:
      type: object
      description: Request body for executing pending actions
      properties:
        actionIds:
          type: array
          items:
            type: string
          description: Array of pending action IDs to execute
          minItems: 1
      required:
        - actionIds

    BienBotExecuteResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  actionId:
                    type: string
                  type:
                    type: string
                  success:
                    type: boolean
                  result:
                    type: object
                    nullable: true
                  errors:
                    type: array
                    items:
                      type: string
            contextUpdates:
              type: object
              description: Entity IDs added to session context from execution results
            session:
              type: object
              properties:
                id:
                  type: string
                context:
                  type: object

    BienBotResumeResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            session:
              $ref: '#/components/schemas/BienBotSession'
            greeting:
              type: object
              properties:
                role:
                  type: string
                  enum: [assistant]
                content:
                  type: string
                  description: Welcome back greeting with session recap
                suggested_next_steps:
                  type: array
                  items:
                    type: string
                  description: 2-3 actionable follow-up suggestions

  parameters:
    experienceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Experience ID
    planId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Plan ID
    userId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: User ID
    destinationId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Destination ID
    photoId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Photo ID
    documentId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Document ID
    planItemId:
      name: itemId
      in: path
      required: true
      schema:
        type: string
      description: Plan item ID
    noteId:
      name: noteId
      in: path
      required: true
      schema:
        type: string
      description: Note ID
    costId:
      name: costId
      in: path
      required: true
      schema:
        type: string
      description: Cost ID
    tokenId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Token ID
    inviteId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Invite ID
    page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for pagination
    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
      description: Number of items per page
    paginate:
      name: paginate
      in: query
      schema:
        type: boolean
        default: false
      description: Whether to use pagination
    searchQuery:
      name: q
      in: query
      schema:
        type: string
      description: Search query string
    searchTypes:
      name: types
      in: query
      schema:
        type: array
        items:
          type: string
          enum: [destination, experience, plan, user]
      description: Types of resources to search
    tag:
      name: tag
      in: query
      schema:
        type: string
      description: Experience tag filter

paths:
  /:
    get:
      summary: API Information
      description: Returns API information and available endpoints
      responses:
        '200':
          description: API information
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  version:
                    type: string
                  frontend:
                    type: object
                  api:
                    type: object

  /health-check:
    get:
      summary: Health Check
      description: Simple health check endpoint
      responses:
        '200':
          description: Service is healthy
          content:
            text/plain:
              schema:
                type: string
                example: OK

  /auth/csrf-token:
    get:
      summary: Get CSRF Token
      description: Generates and returns a CSRF token for the client
      responses:
        '200':
          description: CSRF token generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  csrfToken:
                    type: string

  /auth/facebook:
    get:
      summary: Facebook OAuth Initiation
      description: Initiates Facebook OAuth login flow
      parameters:
        - name: state
          in: query
          schema:
            type: string
          description: CSRF state parameter
      responses:
        '302':
          description: Redirect to Facebook OAuth

  /auth/facebook/callback:
    get:
      summary: Facebook OAuth Callback
      description: Handles Facebook OAuth callback
      responses:
        '302':
          description: Redirect to frontend with OAuth result

  /auth/google:
    get:
      summary: Google OAuth Initiation
      description: Initiates Google OAuth login flow
      responses:
        '302':
          description: Redirect to Google OAuth

  /auth/google/callback:
    get:
      summary: Google OAuth Callback
      description: Handles Google OAuth callback
      responses:
        '302':
          description: Redirect to frontend with OAuth result

  /auth/twitter:
    get:
      summary: Twitter OAuth Initiation
      description: Initiates Twitter OAuth login flow
      responses:
        '302':
          description: Redirect to Twitter OAuth

  /auth/twitter/callback:
    get:
      summary: Twitter OAuth Callback
      description: Handles Twitter OAuth callback
      responses:
        '302':
          description: Redirect to frontend with OAuth result

  /auth/link/facebook:
    get:
      summary: Link Facebook Account
      description: Links Facebook account to existing user
      security:
        - bearerAuth: []
      responses:
        '302':
          description: Redirect to profile settings

  /auth/link/google:
    get:
      summary: Link Google Account
      description: Links Google account to existing user
      security:
        - bearerAuth: []
      responses:
        '302':
          description: Redirect to profile settings

  /auth/link/twitter:
    get:
      summary: Link Twitter Account
      description: Links Twitter account to existing user
      security:
        - bearerAuth: []
      responses:
        '302':
          description: Redirect to profile settings

  /auth/unlink/{provider}:
    delete:
      summary: Unlink Social Account
      description: Removes social account link from user profile
      security:
        - bearerAuth: []
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [facebook, google, twitter]
      responses:
        '200':
          description: Account unlinked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid provider or cannot unlink only auth method
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/linked-accounts:
    get:
      summary: Get Linked Accounts
      description: Returns user's linked social accounts
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Linked accounts information
          content:
            application/json:
              schema:
                type: object
                properties:
                  facebook:
                    type: boolean
                  google:
                    type: boolean
                  twitter:
                    type: boolean
                  hasPassword:
                    type: boolean
                  accounts:
                    type: array
                    items:
                      type: object

  /auth/logout:
    post:
      summary: Logout
      description: Logs out the current user and clears session
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /users:
    post:
      summary: Create User
      description: Creates a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 3
                inviteCode:
                  type: string
              required:
                - name
                - email
                - password
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: Get All Users
      description: Returns a list of all users (admin only)
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/bulk:
    get:
      summary: Get Bulk Users
      description: Returns multiple users by IDs
      security:
        - bearerAuth: []
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: User IDs to fetch
      responses:
        '200':
          description: Bulk user data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/search:
    get:
      summary: Search Users
      description: Searches for users by name or email
      security:
        - bearerAuth: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/profile:
    get:
      summary: Get Current User Profile
      description: Returns the current user's profile information
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /users/{id}:
    parameters:
      - $ref: '#/components/parameters/userId'
    get:
      summary: Get User by ID
      description: Returns a specific user by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update User
      description: Updates user information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                visibility:
                  type: string
                  enum: [private, public]
                preferences:
                  type: object
                  properties:
                    theme:
                      type: string
                      enum: [light, dark, system-default]
                    currency:
                      type: string
                    language:
                      type: string
                    timezone:
                      type: string
                    profileVisibility:
                      type: string
                      enum: [private, public]
                    notifications:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        channels:
                          type: array
                          items:
                            type: string
                            enum: [email, push, sms]
                        types:
                          type: array
                          items:
                            type: string
                            enum: [activity, reminder, marketing, updates]
                location:
                  type: object
                  properties:
                    displayName:
                      type: string
                    city:
                      type: string
                    state:
                      type: string
                    country:
                      type: string
                    countryCode:
                      type: string
                    postalCode:
                      type: string
                    coordinates:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: [Point]
                        coordinates:
                          type: array
                          items:
                            type: number
                            minItems: 2
                            maxItems: 2
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}/admin:
    parameters:
      - $ref: '#/components/parameters/userId'
    put:
      summary: Update User as Admin
      description: Updates user information as an administrator (super admin only)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                isSuperAdmin:
                  type: boolean
                role:
                  type: string
                  enum: [super_admin, regular_user]
                emailConfirmed:
                  type: boolean
                visibility:
                  type: string
                  enum: [private, public]
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions (super admin required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/login:
    post:
      summary: User Login
      description: Authenticates a user and returns a JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
              required:
                - email
                - password
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  user:
                    $ref: '#/components/schemas/User'
                  token:
                    type: string
                    description: JWT token
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/check-token:
    get:
      summary: Check Token Validity
      description: Validates the current JWT token and returns user information
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token is valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/forgot-password:
    post:
      summary: Request Password Reset
      description: Sends a password reset email to the user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
              required:
                - email
      responses:
        '200':
          description: Password reset email sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/reset-password:
    post:
      summary: Reset Password
      description: Resets user password using reset token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                password:
                  type: string
                  minLength: 3
              required:
                - token
                - password
      responses:
        '200':
          description: Password reset successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/confirm-email/{token}:
    get:
      summary: Confirm Email
      description: Confirms user email address using confirmation token
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Email confirmation token
      responses:
        '200':
          description: Email confirmed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/resend-confirmation:
    post:
      summary: Resend Email Confirmation
      description: Resends email confirmation to the current user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Confirmation email sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Email already confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{id}/role:
    parameters:
      - $ref: '#/components/parameters/userId'
    put:
      summary: Update User Role
      description: Updates user role (super admin only)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum: [super_admin, regular_user]
              required:
                - role
      responses:
        '200':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /destinations:
    get:
      summary: Get Destinations
      description: Returns a list of destinations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/searchQuery'
      responses:
        '200':
          description: List of destinations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Destination'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

    post:
      summary: Create Destination
      description: Creates a new destination
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                country:
                  type: string
                  minLength: 1
                description:
                  type: string
              required:
                - name
                - country
      responses:
        '201':
          description: Destination created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /destinations/{id}:
    parameters:
      - $ref: '#/components/parameters/destinationId'
    get:
      summary: Get Destination
      description: Returns a specific destination by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Destination data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Destination'
        '404':
          description: Destination not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update Destination
      description: Updates destination information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                country:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: Destination updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Destination
      description: Deletes a destination
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Destination deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /destinations/{destinationId}/user/{userId}:
    parameters:
      - name: destinationId
        in: path
        required: true
        schema:
          type: string
        description: Destination ID
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User ID
    post:
      summary: Toggle Destination Favorite
      description: Adds or removes a destination from user's favorites
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Favorite status toggled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /experiences:
    get:
      summary: Get Experiences
      description: Returns a list of experiences
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/tag'
      responses:
        '200':
          description: List of experiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

    post:
      summary: Create Experience
      description: Creates a new experience
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                overview:
                  type: string
                destination:
                  type: string
                experience_type:
                  type: array
                  items:
                    type: string
                plan_items:
                  type: array
                  items:
                    $ref: '#/components/schemas/PlanItem'
                visibility:
                  type: string
                  enum: [private, contributors, public]
                  default: public
                difficulty:
                  type: number
                  minimum: 1
                  maximum: 10
                rating:
                  type: number
                  minimum: 0
                  maximum: 5
              required:
                - name
                - destination
      responses:
        '201':
          description: Experience created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Email verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /experiences/tag/{tagSlug}:
    parameters:
      - name: tagSlug
        in: path
        required: true
        schema:
          type: string
        description: Experience tag slug
    get:
      summary: Get Experiences by Tag
      description: Returns experiences filtered by tag
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Experiences with tag
          content:
            application/json:
              schema:
                type: object
                properties:
                  tagName:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

  /experiences/tags:
    get:
      summary: Get Experience Tags
      description: Returns all available experience tags
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /experiences/user/{userId}/created:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User ID
    get:
      summary: Get User's Created Experiences
      description: Returns experiences created by a specific user
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: User's created experiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

  /experiences/user/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User ID
    get:
      summary: Get User's Experiences
      description: Returns experiences accessible to a specific user
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: User's accessible experiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experience'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

  /experiences/{id}:
    parameters:
      - $ref: '#/components/parameters/experienceId'
    get:
      summary: Get Experience
      description: Returns a specific experience by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Experience data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experience'
        '404':
          description: Experience not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update Experience
      description: Updates experience information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                overview:
                  type: string
                destination:
                  type: string
                experience_type:
                  type: array
                  items:
                    type: string
                plan_items:
                  type: array
                  items:
                    $ref: '#/components/schemas/PlanItem'
                visibility:
                  type: string
                  enum: [private, contributors, public]
                difficulty:
                  type: number
                  minimum: 1
                  maximum: 10
                rating:
                  type: number
                  minimum: 0
                  maximum: 5
      responses:
        '200':
          description: Experience updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions or email verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Experience
      description: Deletes an experience and all associated plans
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Experience deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /experiences/{id}/with-context:
    parameters:
      - $ref: '#/components/parameters/experienceId'
    get:
      summary: Get Experience with Context
      description: Returns experience with additional context (user's plan status, permissions, etc.)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Experience with context
          content:
            application/json:
              schema:
                type: object
                properties:
                  experience:
                    $ref: '#/components/schemas/Experience'
                  userPlan:
                    $ref: '#/components/schemas/Plan'
                  permissions:
                    type: object
                    properties:
                      canEdit:
                        type: boolean
                      canDelete:
                        type: boolean
                      canManagePermissions:
                        type: boolean
                      role:
                        type: string
        '404':
          description: Experience not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /experiences/{experienceId}/transfer-ownership:
    parameters:
      - name: experienceId
        in: path
        required: true
        schema:
          type: string
        description: Experience ID
    put:
      summary: Transfer Experience Ownership
      description: Transfers ownership of an experience to another user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newOwnerId:
                  type: string
              required:
                - newOwnerId
      responses:
        '200':
          description: Ownership transferred successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans:
    get:
      summary: Get User Plans
      description: Returns all plans for the current user
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/paginate'
      responses:
        '200':
          description: List of user plans
          content:
            application/json:
              schema:
                oneOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/Plan'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Plan'
                      pagination:
                        type: object
                        properties:
                          page:
                            type: integer
                          limit:
                            type: integer
                          totalCount:
                            type: integer
                          totalPages:
                            type: integer
                          hasMore:
                            type: boolean

  /plans/experience/{experienceId}:
    parameters:
      - name: experienceId
        in: path
        required: true
        schema:
          type: string
        description: Experience ID
    post:
      summary: Create Plan
      description: Creates a new plan for an experience
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                planned_date:
                  type: string
                  format: date
      responses:
        '201':
          description: Plan created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Plan already exists for this experience
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/experience/{experienceId}/all:
    parameters:
      - name: experienceId
        in: path
        required: true
        schema:
          type: string
        description: Experience ID
    get:
      summary: Get All Plans for Experience
      description: Returns all plans for a specific experience
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of plans for the experience
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'

  /plans/experience/{experienceId}/check:
    parameters:
      - name: experienceId
        in: path
        required: true
        schema:
          type: string
        description: Experience ID
    get:
      summary: Check User Plan for Experience
      description: Checks if user has a plan for the experience
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Plan status
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasPlan:
                    type: boolean
                  plans:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
                        isOwn:
                          type: boolean
                        owner:
                          type: string
                  planId:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
                  ownPlanId:
                    type: string

  /plans/{id}:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      summary: Get Plan
      description: Returns a specific plan by ID
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Plan data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update Plan
      description: Updates plan information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                planned_date:
                  type: string
                  format: date
                plan:
                  type: array
                  items:
                    $ref: '#/components/schemas/PlanItemSnapshot'
                notes:
                  type: string
      responses:
        '200':
          description: Plan updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Plan
      description: Deletes a plan
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Plan deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions (only plan owner can delete)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/reorder:
    parameters:
      - $ref: '#/components/parameters/planId'
    put:
      summary: Reorder Plan Items
      description: Updates the order of plan items in a plan
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan:
                  type: array
                  items:
                    $ref: '#/components/schemas/PlanItemSnapshot'
              required:
                - plan
      responses:
        '200':
          description: Plan items reordered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/items:
    parameters:
      - $ref: '#/components/parameters/planId'
    post:
      summary: Add Plan Item
      description: Adds a new item to a plan
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                url:
                  type: string
                cost:
                  type: number
                planning_days:
                  type: number
                parent:
                  type: string
                activity_type:
                  type: string
                  enum: [accommodation, transport, food, drinks, coffee, sightseeing, museum, nature, adventure, sports, entertainment, wellness, tour, class, nightlife, religious, local, shopping, market, health, banking, communication, admin, laundry, rental, photography, meeting, work, rest, packing, checkpoint, custom, null]
                location:
                  $ref: '#/components/schemas/Location'
                plan_item_id:
                  type: string
              required:
                - text
      responses:
        '200':
          description: Plan item added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/items/{itemId}:
    parameters:
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/planItemId'
    patch:
      summary: Update Plan Item
      description: Updates a specific plan item
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                complete:
                  type: boolean
                cost:
                  type: number
                planning_days:
                  type: number
                text:
                  type: string
                url:
                  type: string
                activity_type:
                  type: string
                  enum: [accommodation, transport, food, drinks, coffee, sightseeing, museum, nature, adventure, sports, entertainment, wellness, tour, class, nightlife, religious, local, shopping, market, health, banking, communication, admin, laundry, rental, photography, meeting, work, rest, packing, checkpoint, custom, null]
                scheduled_date:
                  type: string
                  format: date
                scheduled_time:
                  type: string
                location:
                  $ref: '#/components/schemas/Location'
      responses:
        '200':
          description: Plan item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Plan Item
      description: Deletes a plan item and its children
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Plan item deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/collaborators:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      summary: Get Plan Collaborators
      description: Returns all collaborators for a plan
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of collaborators
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/permissions/collaborator:
    parameters:
      - $ref: '#/components/parameters/planId'
    post:
      summary: Add Collaborator
      description: Adds a collaborator to a plan
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
              required:
                - userId
      responses:
        '200':
          description: Collaborator added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Remove Collaborator
      description: Removes a collaborator from a plan
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID of collaborator to remove
      responses:
        '200':
          description: Collaborator removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/items/{itemId}/notes:
    parameters:
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/planItemId'
    post:
      summary: Add Plan Item Note
      description: Adds a note to a plan item
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  minLength: 1
              required:
                - content
      responses:
        '200':
          description: Note added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/items/{itemId}/notes/{noteId}:
    parameters:
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/planItemId'
      - $ref: '#/components/parameters/noteId'
    patch:
      summary: Update Plan Item Note
      description: Updates a note on a plan item (note author only)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  minLength: 1
              required:
                - content
      responses:
        '200':
          description: Note updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions (only note author can update)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Plan Item Note
      description: Deletes a note from a plan item (note author only)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Note deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions (only note author can delete)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/items/{itemId}/assign:
    parameters:
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/planItemId'
    post:
      summary: Assign Plan Item
      description: Assigns a plan item to a collaborator
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                assignedTo:
                  type: string
              required:
                - assignedTo
      responses:
        '200':
          description: Plan item assigned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Unassign Plan Item
      description: Removes assignment from a plan item
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Plan item unassigned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/costs:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      summary: Get Plan Costs
      description: Returns all costs for a plan
      security:
        - bearerAuth: []
      parameters:
        - name: filter
          in: query
          schema:
            type: string
            enum: [all, item, collaborator, plan]
            default: all
          description: Filter costs by type
      responses:
        '200':
          description: List of costs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cost'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Add Cost
      description: Adds a cost entry to a plan
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                description:
                  type: string
                cost:
                  type: number
                  minimum: 0
                currency:
                  type: string
                  default: USD
                category:
                  type: string
                  enum: [accommodation, transport, food, activities, equipment, other]
                  description: Cost category for grouping and reporting
                date:
                  type: string
                  format: date-time
                  description: Date when the cost was incurred
                plan_item:
                  type: string
                collaborator:
                  type: string
              required:
                - title
                - cost
      responses:
        '200':
          description: Cost added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/costs/{costId}:
    parameters:
      - $ref: '#/components/parameters/planId'
      - $ref: '#/components/parameters/costId'
    patch:
      summary: Update Cost
      description: Updates a cost entry
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                cost:
                  type: number
                  minimum: 0
                currency:
                  type: string
                category:
                  type: string
                  enum: [accommodation, transport, food, activities, equipment, other, null]
                  description: Cost category for grouping and reporting
                date:
                  type: string
                  format: date-time
                  description: Date when the cost was incurred
                plan_item:
                  type: string
                collaborator:
                  type: string
      responses:
        '200':
          description: Cost updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Cost not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Cost
      description: Deletes a cost entry
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Cost deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Cost not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/preview:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      summary: Get Plan Preview
      description: |
        Returns minimal, non-sensitive plan metadata for access-denied screens.
        No authentication required. Used to display plan owner name and experience name
        when a user encounters a plan they don't have access to.
      responses:
        '200':
          description: Plan preview retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          planId:
                            type: string
                          experienceName:
                            type: string
                          ownerFirstName:
                            type: string
                          experienceId:
                            type: string
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/access-requests:
    parameters:
      - $ref: '#/components/parameters/planId'
    post:
      summary: Request Plan Access
      description: |
        Submit an access request to the plan owner. Requires the plan owner to have the
        `plan_access_requests` feature flag enabled. If the user already has access or
        an existing pending request, appropriate errors are returned. An email notification
        with an approval token link is sent to the plan owner.
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: Optional message to include with the access request
      responses:
        '200':
          description: Access request submitted (or updated if a pending request already exists)
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AccessRequest'
        '400':
          description: User already has access, or invalid plan ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Plan access requests not enabled for this plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Access request already exists and has been processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: Get Access Requests
      description: |
        Retrieve access requests for a plan. Only the plan owner or super admin can view.
        By default returns only pending requests. Pass `?all=true` to include all statuses.
      security:
        - bearerAuth: []
      parameters:
        - name: all
          in: query
          schema:
            type: string
            enum: ['true', 'false']
          description: When 'true', returns all requests including approved/declined
      responses:
        '200':
          description: Access requests retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccessRequest'
        '403':
          description: Only plan owner can view access requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/access-requests/{requestId}:
    parameters:
      - $ref: '#/components/parameters/planId'
      - name: requestId
        in: path
        required: true
        schema:
          type: string
        description: Access request ID
    patch:
      summary: Respond to Access Request
      description: |
        Approve or decline a pending access request. Only the plan owner or super admin
        can respond. Approving adds the requester as a collaborator on the plan.
        The requester is notified of the decision via email and BienBot.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum: [approve, decline]
                  description: Whether to approve or decline the access request
      responses:
        '200':
          description: Access request responded to
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AccessRequest'
        '400':
          description: Invalid action or request already processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Only plan owner can respond to access requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan or access request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /plans/{id}/access-requests/approve-by-token:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      summary: Approve Access Request via Token
      description: |
        Token-based one-click approval from email link. No authentication required.
        Redirects to the plan URL on success, or the frontend with error query params
        on failure. Token is single-use and expires after 7 days.
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Approval token from the email notification
      responses:
        '302':
          description: Redirects to plan URL (success) or frontend with error (failure)
          headers:
            Location:
              schema:
                type: string
              description: Redirect URL

  /photos:
    post:
      summary: Upload Photo
      description: Uploads a single photo file
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: Image file (JPEG, PNG, WebP, max 10MB)
              required:
                - image
      responses:
        '201':
          description: Photo uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid file format or size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /photos/batch:
    post:
      summary: Upload Multiple Photos
      description: Uploads multiple photo files at once
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Image files (JPEG, PNG, WebP, max 10MB each, max 10 files)
              required:
                - images
      responses:
        '201':
          description: Photos uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid file format or size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /photos/url:
    post:
      summary: Create Photo from URL
      description: Creates a photo from a URL
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                caption:
                  type: string
              required:
                - url
      responses:
        '201':
          description: Photo created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid URL or format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /photos/{id}:
    parameters:
      - $ref: '#/components/parameters/photoId'
    get:
      summary: Get Photo
      description: Returns photo metadata (not the actual image file)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Photo metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
        '404':
          description: Photo not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Update Photo
      description: Updates photo metadata
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                caption:
                  type: string
      responses:
        '200':
          description: Photo updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete Photo
      description: Deletes a photo
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Photo deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /photos/{id}/permissions/collaborator:
    parameters:
      - $ref: '#/components/parameters/photoId'
    post:
      summary: Add Photo Collaborator
      description: Adds a collaborator to a photo
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
              required:
                - userId
      responses:
        '200':
          description: Collaborator added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Remove Photo Collaborator
      description: Removes a collaborator from a photo
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID of collaborator to remove
      responses:
        '200':
          description: Collaborator removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /photos/{id}/permissions/contributor:
    parameters:
      - $ref: '#/components/parameters/photoId'
    post:
      summary: Add Photo Contributor
      description: Adds a contributor to a photo
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
              required:
                - userId
      responses:
        '200':
          description: Contributor added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Remove Photo Contributor
      description: Removes a contributor from a photo
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID of contributor to remove
      responses:
        '200':
          description: Contributor removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /search:
    get:
      summary: Global Search
      description: Searches across all collections (destinations, experiences, plans, users)
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/searchTypes'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'

  /search/destinations:
    get:
      summary: Search Destinations
      description: Searches destinations by name or country
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Destination search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Destination'

  /search/experiences:
    get:
      summary: Search Experiences
      description: Searches experiences by name, overview, or tags
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Experience search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Experience'

  /search/plans:
    get:
      summary: Search Plans
      description: Searches plans by experience name or notes
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Plan search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'

  /search/users:
    get:
      summary: Search Users
      description: Searches users by name or email
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/searchQuery'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: User search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /dashboard:
    get:
      summary: Get Dashboard
      description: Returns user's dashboard with stats, recent activity, and upcoming plans
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'

  /dashboard/activity-feed:
    get:
      summary: Get Activity Feed
      description: |
        Returns the authenticated user's enriched activity feed with pagination.
        Activities include human-readable text, deep links, and actor photo URLs.
        Supports filtering by action types and resource types.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
        - name: actions
          in: query
          schema:
            type: array
            items:
              type: string
          description: Filter by action types (e.g., plan_created, resource_updated)
        - name: resourceTypes
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [Experience, Destination, Plan, User]
          description: Filter by resource types
      responses:
        '200':
          description: Enriched activity feed with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  activities:
                    type: array
                    items:
                      $ref: '#/components/schemas/EnrichedActivityFeedItem'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean

  /dashboard/upcoming-plans:
    get:
      summary: Get Upcoming Plans
      description: Returns user's upcoming plans
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Upcoming plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plan'

  /tokens:
    get:
      summary: Get API Tokens
      description: Returns all API tokens for the current user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of API tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Token'

    post:
      summary: Create API Token
      description: Creates a new API token
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                permissions:
                  type: array
                  items:
                    type: string
                    enum: [read, write, admin]
                  default: [read]
                expiresAt:
                  type: string
                  format: date-time
              required:
                - name
      responses:
        '201':
          description: Token created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  token:
                    type: string
                    description: The actual API token (only shown once)
                  tokenData:
                    $ref: '#/components/schemas/Token'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /tokens/{id}:
    parameters:
      - $ref: '#/components/parameters/tokenId'
    delete:
      summary: Delete API Token
      description: Deletes an API token
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /invites:
    get:
      summary: Get Sent Invites
      description: Returns invites sent by the current user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of sent invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invite'

    post:
      summary: Send Invite
      description: Sends an invitation to join the platform
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                message:
                  type: string
              required:
                - email
      responses:
        '201':
          description: Invite sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: User already exists or invite already sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /invites/{id}:
    parameters:
      - $ref: '#/components/parameters/inviteId'
    delete:
      summary: Cancel Invite
      description: Cancels a pending invite
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Invite cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Invite not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /invite-tracking/{code}:
    get:
      summary: Track Invite
      description: Tracks invite usage and redirects appropriately
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          description: Invite code
      responses:
        '302':
          description: Redirect to signup or login
        '404':
          description: Invalid invite code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /activities:
    get:
      summary: Get All Activities (Admin)
      description: Returns all activities with optional filtering. Requires super admin access.
      tags:
        - Activities
      security:
        - bearerAuth: []
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [user, resource, all]
            default: user
          description: Activity scope
        - name: resourceType
          in: query
          schema:
            type: string
            enum: [User, Destination, Experience, Plan, Photo, Document]
          description: Filter by resource type
        - name: resourceId
          in: query
          schema:
            type: string
          description: Filter by specific resource ID
        - name: action
          in: query
          schema:
            type: string
          description: Filter by action type
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Activity feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasMore:
                        type: boolean
        '403':
          description: Requires super admin access

  /activities/stats:
    get:
      summary: Get Activity Statistics (Admin)
      description: Returns aggregated activity statistics. Requires super admin access.
      tags:
        - Activities
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Activity statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
        '403':
          description: Requires super admin access

  /activities/experience/{experienceId}/feed:
    get:
      summary: Get Experience Activity Feed
      description: |
        Returns the public activity feed for an experience.
        Shows entries like planning activity, photo uploads, and visibility changes.
        Uses cursor-based pagination.
      tags:
        - Activities
      security:
        - bearerAuth: []
      parameters:
        - name: experienceId
          in: path
          required: true
          schema:
            type: string
          description: Experience ID
        - name: limit
          in: query
          schema:
            type: integer
            default: 30
          description: Number of activities to return
        - name: before
          in: query
          schema:
            type: string
            format: date-time
          description: Cursor-based pagination - return activities before this timestamp
      responses:
        '200':
          description: Experience activity feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  activities:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  hasMore:
                    type: boolean

  /activities/resource/{resourceId}:
    get:
      summary: Get Resource History
      description: Returns activity history for a specific resource. Requires owner, collaborator, or admin access.
      tags:
        - Activities
      security:
        - bearerAuth: []
      parameters:
        - name: resourceId
          in: path
          required: true
          schema:
            type: string
          description: Resource ID
      responses:
        '200':
          description: Resource activity history
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'

  /activities/actor/{actorId}:
    get:
      summary: Get Actor History
      description: Returns activity history for a specific user. Requires self or admin access.
      tags:
        - Activities
      security:
        - bearerAuth: []
      parameters:
        - name: actorId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: User activity history
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'

  /activities/curator/planners:
    get:
      summary: Get Curator Planners
      description: Returns users who have planned the curator's experiences. Requires curator feature flag.
      tags:
        - Activities
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of users who planned curator's experiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '403':
          description: Requires curator feature flag

  # Document endpoints
  /documents/supported-types:
    get:
      summary: Get Supported Document Types
      description: Returns list of supported document types and size limits
      tags:
        - Documents
      responses:
        '200':
          description: Supported document types
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      pdf:
                        type: object
                        properties:
                          maxSize:
                            type: integer
                          mimeTypes:
                            type: array
                            items:
                              type: string
                      image:
                        type: object
                        properties:
                          maxSize:
                            type: integer
                          mimeTypes:
                            type: array
                            items:
                              type: string
                      word:
                        type: object
                        properties:
                          maxSize:
                            type: integer
                          mimeTypes:
                            type: array
                            items:
                              type: string
                      text:
                        type: object
                        properties:
                          maxSize:
                            type: integer
                          mimeTypes:
                            type: array
                            items:
                              type: string

  /documents:
    post:
      summary: Upload Document
      description: Upload and process a document with optional AI parsing
      tags:
        - Documents
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - document
                - entityType
                - entityId
              properties:
                document:
                  type: string
                  format: binary
                  description: Document file (PDF, image, Word, or text)
                entityType:
                  type: string
                  enum: [plan, plan_item, experience, destination]
                entityId:
                  type: string
                  description: ID of the entity to attach document to
                planId:
                  type: string
                  description: Required when entityType is plan_item
                planItemId:
                  type: string
                  description: Optional plan item reference
                aiParsingEnabled:
                  type: boolean
                  default: true
                documentTypeHint:
                  type: string
                  enum: [flight, hotel, activity, restaurant, transport, travel]
                language:
                  type: string
                  default: eng
                forceLLM:
                  type: boolean
                skipLLMFallback:
                  type: boolean
      responses:
        '201':
          description: Document uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: Invalid request or unsupported file type
        '401':
          description: Unauthorized
        '413':
          description: File too large

  /documents/{id}:
    get:
      summary: Get Document
      description: Get a document by ID
      tags:
        - Documents
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Document details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '401':
          description: Unauthorized
        '403':
          description: Insufficient permissions
        '404':
          description: Document not found
    delete:
      summary: Delete Document
      description: Delete a document (owner only)
      tags:
        - Documents
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Document deleted
        '401':
          description: Unauthorized
        '403':
          description: Only document owner can delete
        '404':
          description: Document not found

  /documents/entity/{entityType}/{entityId}:
    get:
      summary: Get Documents by Entity
      description: Get all documents attached to an entity
      tags:
        - Documents
      security:
        - bearerAuth: []
      parameters:
        - name: entityType
          in: path
          required: true
          schema:
            type: string
            enum: [plan, plan_item, experience, destination]
        - name: entityId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
        '401':
          description: Unauthorized
        '403':
          description: Insufficient permissions

  /documents/{id}/reprocess:
    post:
      summary: Reprocess Document
      description: Re-extract text and/or re-parse document with AI
      tags:
        - Documents
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                language:
                  type: string
                forceLLM:
                  type: boolean
                skipLLMFallback:
                  type: boolean
                documentTypeHint:
                  type: string
      responses:
        '200':
          description: Document reprocessed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: Cannot reprocess - max attempts reached
        '401':
          description: Unauthorized
        '403':
          description: Insufficient permissions
        '404':
          description: Document not found

  /follows/feed:
    get:
      summary: Get Follow Feed
      description: |
        Returns enriched activity feed from users the authenticated user follows.
        Activities include human-readable text, deep links, and actor photo URLs.
        Supports filtering by action types and resource types.
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          description: Number of activities to return
        - name: skip
          in: query
          schema:
            type: integer
            default: 0
          description: Number of activities to skip
        - name: actions
          in: query
          schema:
            type: string
          description: Comma-separated list of action types to filter by
        - name: resourceTypes
          in: query
          schema:
            type: string
          description: Comma-separated list of resource types to filter by
      responses:
        '200':
          description: Enriched follow activity feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  feed:
                    type: array
                    items:
                      $ref: '#/components/schemas/EnrichedActivityFeedItem'
                  total:
                    type: integer
                  limit:
                    type: integer
                  skip:
                    type: integer
                  followingCount:
                    type: integer

  /follows/requests:
    get:
      summary: Get Follow Requests
      description: Returns pending follow requests for private profile users
      tags:
        - Follows
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Pending follow requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  requests:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        follower:
                          $ref: '#/components/schemas/User'
                        status:
                          type: string
                          enum: [pending, accepted, blocked]
                        createdAt:
                          type: string
                          format: date-time

  /follows/requests/count:
    get:
      summary: Get Follow Request Count
      description: Returns count of pending follow requests
      tags:
        - Follows
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Request count
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  count:
                    type: integer

  /follows/requests/{followerId}/accept:
    put:
      summary: Accept Follow Request
      description: Accepts a pending follow request
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: followerId
          in: path
          required: true
          schema:
            type: string
          description: Follower user ID
      responses:
        '200':
          description: Follow request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /follows/requests/{followerId}:
    delete:
      summary: Reject Follow Request
      description: Rejects a pending follow request
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: followerId
          in: path
          required: true
          schema:
            type: string
          description: Follower user ID
      responses:
        '200':
          description: Follow request rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /follows/{userId}:
    post:
      summary: Follow User
      description: |
        Follows another user. For private profiles, creates a pending follow request.

        **Idempotent** — if the authenticated user is already following the target, returns
        `200 { success: true, message: 'Already following' }` instead of an error.
        This prevents spurious failures on double-tap or rapid UI interactions.
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID to follow
      responses:
        '200':
          description: Already following (idempotent — no action taken)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Already following
        '201':
          description: User followed successfully (or request sent for private profiles)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Validation error (e.g. cannot follow self, or pending request already exists)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Unfollow User
      description: |
        Unfollows a user.

        **Idempotent** — if the authenticated user is not currently following the target,
        returns `200 { success: true, message: 'Not following' }` instead of a 404 error.
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID to unfollow
      responses:
        '200':
          description: User unfollowed successfully (or was not following — idempotent)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Unfollowed successfully
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /follows/{userId}/followers:
    get:
      summary: Get Followers
      description: Returns list of users who follow the specified user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Followers list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  followers:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer

  /follows/{userId}/following:
    get:
      summary: Get Following
      description: Returns list of users the specified user follows
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Following list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  following:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer

  /follows/{userId}/counts:
    get:
      summary: Get Follow Counts
      description: Returns follower and following counts for a user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Follow counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  followers:
                    type: integer
                  following:
                    type: integer

  /follows/{userId}/status:
    get:
      summary: Get Follow Status
      description: Check whether the authenticated user follows the specified user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Follow status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  isFollowing:
                    type: boolean
                  status:
                    type: string
                    enum: [following, pending, not_following]

  /follows/{userId}/relationship:
    get:
      summary: Get Follow Relationship
      description: Returns the mutual follow relationship between the authenticated user and the specified user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID
      responses:
        '200':
          description: Mutual follow relationship
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  isFollowing:
                    type: boolean
                  isFollowedBy:
                    type: boolean

  /follows/{userId}/remove-follower:
    delete:
      summary: Remove Follower
      description: Removes a user from the authenticated user's followers list
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: Follower user ID to remove
      responses:
        '200':
          description: Follower removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  /follows/{userId}/block:
    post:
      summary: Block Follower
      description: Blocks a user from following the authenticated user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID to block
      responses:
        '200':
          description: User blocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

    delete:
      summary: Unblock Follower
      description: Unblocks a previously blocked user
      tags:
        - Follows
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID to unblock
      responses:
        '200':
          description: User unblocked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'

  # Chat API Endpoints
  # These endpoints require the 'chat' feature flag (evaluated on plan owner for plan/plan-item channels).
  # Powered by Stream Chat. All endpoints require authentication.

  /chat/token:
    post:
      summary: Get Chat Token
      description: |
        Generate a Stream Chat user token for the authenticated user.
        Used to initialize the Stream Chat client on the frontend.
      tags:
        - Chat
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token generated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          token:
                            type: string
                            description: Stream Chat JWT token
                          user:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
        '501':
          description: Chat service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /chat/channels/dm:
    post:
      summary: Create or Get DM Channel
      description: |
        Create or retrieve a direct message channel between the authenticated user and
        another user. DM eligibility requires one of:
        1. Actor is a super admin
        2. Users mutually follow each other
        3. Actor is a curator AND target has planned one of actor's experiences

        Channel IDs are deterministic (sorted user IDs).
      tags:
        - Chat
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - otherUserId
              properties:
                otherUserId:
                  type: string
                  description: User ID of the other participant
      responses:
        '200':
          description: DM channel ready
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ChatChannel'
        '403':
          description: DM eligibility not met
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Chat service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /chat/channels/plan:
    post:
      summary: Create or Get Plan Channel
      description: |
        Create or retrieve a group chat channel for a plan. Requires the plan owner
        to have the `chat` feature flag enabled. Only users with plan access
        (owner or collaborator) can join. Channel name format: "{Experience Name} - {Owner Name}".
      tags:
        - Chat
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - planId
              properties:
                planId:
                  type: string
                  description: Plan ID
      responses:
        '200':
          description: Plan channel ready
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ChatChannel'
        '403':
          description: Chat not enabled for this plan or user not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Chat service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /chat/channels/plan-item:
    post:
      summary: Create or Get Plan Item Channel
      description: |
        Create or retrieve a group chat channel for a specific plan item.
        Same access rules as plan channel. Channel name format: "{Experience Name} - {Plan Item Text}".
        Channel ID format: `planItem_{planId}_{planItemId}`.
      tags:
        - Chat
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - planId
                - planItemId
              properties:
                planId:
                  type: string
                  description: Plan ID
                planItemId:
                  type: string
                  description: Plan item ID
      responses:
        '200':
          description: Plan item channel ready
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ChatChannel'
        '403':
          description: Chat not enabled or not authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Plan or plan item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Chat service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /chat/channels/bienbot:
    delete:
      summary: Cancel BienBot Channel
      description: |
        Delete the BienBot (AI assistant) chat channel for the authenticated user.
        Used when a user wants to dismiss or reset their BienBot conversation.
      tags:
        - Chat
      security:
        - bearerAuth: []
      responses:
        '200':
          description: BienBot channel cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '501':
          description: Chat service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # AI API Endpoints
  # These endpoints require the 'ai_features' feature flag to be enabled for the user

  /ai/status:
    get:
      summary: Get AI Status
      description: Check AI service availability and configured providers
      tags:
        - AI
      security:
        - bearerAuth: []
      responses:
        '200':
          description: AI status information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/complete:
    post:
      summary: AI Completion
      description: |
        General AI text completion. Requires the 'ai_features' feature flag.
        Rate limited to 100 requests per 15 minutes.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AICompletionRequest'
      responses:
        '200':
          description: AI completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/autocomplete:
    post:
      summary: AI Autocomplete
      description: |
        Autocomplete text with AI suggestions. Requires the 'ai_features' feature flag.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Text to autocomplete
                context:
                  type: string
                  description: Optional context for better suggestions
                options:
                  type: object
                  properties:
                    provider:
                      type: string
                      enum: [openai, anthropic, mistral, gemini]
                    temperature:
                      type: number
                      minimum: 0
                      maximum: 1
              required:
                - text
      responses:
        '200':
          description: Autocomplete suggestion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/improve:
    post:
      summary: Improve Text
      description: |
        Improve text description quality. Requires the 'ai_features' feature flag.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Text to improve
                type:
                  type: string
                  enum: [experience, destination, plan, general]
                  default: general
                  description: Type of content for context-aware improvements
                options:
                  type: object
              required:
                - text
      responses:
        '200':
          description: Improved text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/translate:
    post:
      summary: Translate Text
      description: |
        Translate text to another language. Requires the 'ai_features' feature flag.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Text to translate
                targetLanguage:
                  type: string
                  description: Target language code or name
                sourceLanguage:
                  type: string
                  description: Optional source language (auto-detected if not provided)
                options:
                  type: object
              required:
                - text
                - targetLanguage
      responses:
        '200':
          description: Translated text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/summarize:
    post:
      summary: Summarize Text
      description: |
        Summarize text content. Requires the 'ai_features' feature flag.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Text to summarize
                maxLength:
                  type: integer
                  description: Maximum length of summary in characters
                options:
                  type: object
              required:
                - text
      responses:
        '200':
          description: Summarized text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ai/generate-tips:
    post:
      summary: Generate Travel Tips
      description: |
        Generate travel tips for a destination. Requires the 'ai_features' feature flag.
      tags:
        - AI
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destination:
                  type: string
                  description: Destination name
                category:
                  type: string
                  enum: [general, food, safety, transport, culture]
                  default: general
                  description: Category of tips to generate
                count:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 5
                  description: Number of tips to generate
                options:
                  type: object
              required:
                - destination
      responses:
        '200':
          description: Generated travel tips
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AICompletionResponse'
        '403':
          description: Feature flag 'ai_features' not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /countries/{countryName}:
    get:
      summary: Get Destinations by Country
      description: Returns all destinations in a specific country with optional search and pagination
      tags:
        - Countries
      parameters:
        - name: countryName
          in: path
          required: true
          schema:
            type: string
          description: Country name (case-insensitive, URL encoded)
        - name: q
          in: query
          schema:
            type: string
          description: Search query to filter destinations by name
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of destinations in the country
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      country:
                        type: string
                        description: Normalized country name
                      destinations:
                        type: array
                        items:
                          $ref: '#/components/schemas/Destination'
                      pagination:
                        type: object
                        properties:
                          page:
                            type: integer
                          limit:
                            type: integer
                          totalCount:
                            type: integer
                          totalPages:
                            type: integer
                          hasMore:
                            type: boolean
        '404':
          description: No destinations found for country
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /geocode:
    post:
      summary: Geocode Address
      description: Converts an address string to coordinates using Google Geocoding API
      tags:
        - Geocoding
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  description: Address string to geocode
              required:
                - address
      responses:
        '200':
          description: Geocoded location data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      address:
                        type: string
                        description: Formatted address from geocoding
                      city:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                      postalCode:
                        type: string
                      placeId:
                        type: string
                        description: Google Places ID
                      geo:
                        type: object
                        properties:
                          type:
                            type: string
                            enum: [Point]
                          coordinates:
                            type: array
                            items:
                              type: number
                            description: "[longitude, latitude]"
        '400':
          description: Address is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Location not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # BienBot AI Assistant Endpoints
  # All endpoints require authentication, the 'ai_features' feature flag, and are rate limited (30 req/15 min)

  /bienbot/chat:
    post:
      summary: BienBot Chat
      description: |
        Main chat endpoint for the BienBot AI assistant. Runs the full pipeline:
        classify intent, build context, call LLM, parse structured response, store session,
        and stream the response via Server-Sent Events (SSE).

        **Peer exchange (shared comments):**
        Messages are routed to the shared-comment path (bypassing the LLM) when:
        - The sender is a session collaborator (non-owner), or
        - The message starts with the `/message` slash command (e.g. `/message @Alice hey!`), or
        - The message is a direct reply to a collaborator message.
        The `/message` prefix is stripped before the content is saved.
        Shared-comment messages receive `message_type: 'shared_comment'` and `sent_by` (sender ObjectId).

        **SSE Events:**
        - `session` — `{ sessionId, title }` (sent first)
        - `token` — `{ text }` (repeated, ~50 char chunks)
        - `actions` — `{ pending_actions }` (if LLM proposes actions)
        - `done` — `{ usage, intent, confidence }` (signals completion)

        Rate limited to 30 requests per 15 minutes. Super admins bypass rate limiting.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BienBotChatRequest'
      responses:
        '200':
          description: SSE stream of chat response
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream with session, token, actions, and done events
        '400':
          description: Invalid request (missing message, invalid sessionId, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Feature flag not enabled or no permission to view entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: AI service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /bienbot/sessions:
    get:
      summary: List BienBot Sessions
      description: |
        List BienBot sessions for the authenticated user, most recent first.
        Optionally filter by status (active or archived).
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [active, archived]
          description: Filter sessions by status
      responses:
        '200':
          description: List of sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      sessions:
                        type: array
                        items:
                          $ref: '#/components/schemas/BienBotSession'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Feature flag not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /bienbot/sessions/{id}:
    get:
      summary: Get BienBot Session
      description: Get a single BienBot session by ID. Only the session owner can access it.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID
      responses:
        '200':
          description: Session details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      session:
                        $ref: '#/components/schemas/BienBotSession'
        '400':
          description: Invalid session ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete BienBot Session
      description: |
        Archive a BienBot session (soft delete). The session is not permanently deleted
        but set to 'archived' status and excluded from default session listing.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID
      responses:
        '200':
          description: Session archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid session ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /bienbot/sessions/{id}/resume:
    post:
      summary: Resume BienBot Session
      description: |
        Resume a past BienBot session. Generates or returns a cached summary of the
        conversation history and a greeting message with suggested next steps.

        - Sessions with < 3 messages return a static "Welcome back!" greeting.
        - Longer sessions run the session summarizer (LLM call).
        - Summaries are cached with a 6-hour TTL.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID
      responses:
        '200':
          description: Session resumed with greeting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BienBotResumeResponse'
        '400':
          description: Invalid session ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /bienbot/sessions/{id}/execute:
    post:
      summary: Execute BienBot Pending Actions
      description: |
        Execute one or more pending actions from a BienBot session. Each action is
        validated against the session's pending_actions list and delegated to the
        appropriate controller (destinations, experiences, plans, etc.).

        Results include per-action success/failure status and any entity IDs added
        to the session context.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BienBotExecuteRequest'
      responses:
        '200':
          description: Actions executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BienBotExecuteResponse'
        '400':
          description: Invalid action IDs or already executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /bienbot/sessions/{id}/pending/{actionId}:
    delete:
      summary: Cancel BienBot Pending Action
      description: Remove a specific pending action from a BienBot session without executing it.
      tags:
        - BienBot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID
        - name: actionId
          in: path
          required: true
          schema:
            type: string
          description: Pending action ID to remove
      responses:
        '200':
          description: Pending action removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          description: Invalid session ID or action ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session or action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'