[Goto Home](/docs/index.html)

# 🔒 GET `/smart-matches`

## Description

- Returns all smart matches where the authenticated user is either `userA` or `userB`
- Only returns matches where `suggested` is `true` and `status` is `pending` or `accepted`
- No pagination

## Response Body

```json
{
  "smartMatches": [
    {
      "_id": "66b72a4f9f8c4f001f3e6a20",
      "id": "alice_johnson:michael_chen",
      "userA": {
        "user": {
          "_id": "66b72a4f9f8c4f001f3e6a11",
          "name": "Alice Johnson",
          "username": "alice_johnson",
          "photo": "https://example.com/photo.jpg",
          "bio": "Coffee lover and aspiring engineer"
        },
        "response": "yes",
        "responseAt": "2026-04-03T10:00:00.000Z"
      },
      "userB": {
        "user": {
          "_id": "66b72a4f9f8c4f001f3e6a12",
          "name": "Michael Chen",
          "username": "michael_chen",
          "photo": "https://example.com/photo2.jpg",
          "bio": "iOS engineer @TechWorld"
        }
      },
      "score": 78,
      "scores": {
        "energy": 24,
        "values": 25,
        "activity": 15,
        "intent": 10
      },
      "status": "pending",
      "community": "66b72a4f9f8c4f001f3e6a01",
      "suggested": true,
      "suggestedAt": "2026-04-01T10:00:00.000Z",
      "expiredAt": "2026-04-08T10:00:00.000Z",
      "clickReason": "You both value curiosity & honesty",
      "sharedEnergy": "Deep 1-on-1",
      "activityIdea": "coffee",
      "conversationStarter": "What's a topic you could talk about for hours without getting bored?",
      "createdAt": "2026-03-25T08:00:00.000Z",
      "updatedAt": "2026-04-01T10:00:00.000Z"
    }
  ]
}
```

# 🔒 GET `/smart-matches/:id`

## Description

- Returns a single smart match by its `_id`
- The authenticated user must be either `userA` or `userB` of that match
- Only returns the match if `suggested` is `true` and `status` is `pending` or `accepted`
- Returns `404` if not found or the user doesn't belong to the match

## Request Params

- **id** - MongoDB ObjectId of the smart match

## Response Body

```json
{
  "smartMatch": {
    "_id": "66b72a4f9f8c4f001f3e6a20",
    "id": "alice_johnson:michael_chen",
    "userA": {
      "user": {
        "_id": "66b72a4f9f8c4f001f3e6a11",
        "name": "Alice Johnson",
        "username": "alice_johnson",
        "photo": "https://example.com/photo.jpg"
      },
      "response": "yes",
      "responseAt": "2026-04-03T10:00:00.000Z"
    },
    "userB": {
      "user": {
        "_id": "66b72a4f9f8c4f001f3e6a12",
        "name": "Michael Chen",
        "username": "michael_chen",
        "photo": "https://example.com/photo2.jpg"
      }
    },
    "score": 78,
    "scores": {
      "energy": 24,
      "values": 25,
      "activity": 15,
      "intent": 10
    },
    "status": "pending",
    "community": "66b72a4f9f8c4f001f3e6a01",
    "suggested": true,
    "suggestedAt": "2026-04-01T10:00:00.000Z",
    "expiredAt": "2026-04-08T10:00:00.000Z",
    "clickReason": "You both value curiosity & honesty",
    "sharedEnergy": "Deep 1-on-1",
    "activityIdea": "coffee",
    "conversationStarter": "What's a topic you could talk about for hours without getting bored?",
    "createdAt": "2026-03-25T08:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
}
```

# 🔒 POST `/smart-matches/:id/accept`

## Description

- Accepts a smart match
- The authenticated user must be either `userA` or `userB` of that match
- Smart match must be `pending`
- Sets the user's `response` to `yes` and `responseAt` to now
- Socket notifies both users with event `smart-match-accepted`
- Push notifies the other user with event `smart-match-accepted`
- **If the other user has not accepted yet:** only updates the user's response; status remains `pending`
- **If the other user has already accepted:**
  - Sets `status` to `accepted` and `acceptedAt` to now
  - Finds the existing one-to-one chat between both users, or creates a new one if none exists; sets `isVibeon: true` on it
  - Socket notifies both users with `chat-created` (new chat) or `chat-updated` (existing chat)
  - Posts 4 messages in the chat and socket notifies both users with `message-received` for each:
    1. Personalized Vibeon intro message (`isVibeon: true`) — Based on shared values/energy (e.g., *"Hey there! 👋 Please meet each other. You both value growth & authenticity."*)
    2. Vibeon conversation message (`isVibeon: true`, `isConversation: true`) — Conversation starter question (e.g., *"What's a topic you could talk about for hours without getting bored?"*)
    3. Vibeon closer message (`isVibeon: true`) — *"I'll leave it to you"*
    4. System message (`system: "chat-access-removed"`) — *"Vibeon left the chat"*
  - Schedules a `smart-match-feedback` notification for both users 36 hours after chat creation
- Returns `404` if not found, user doesn't belong to the match, or match is not `pending`

## Request Params

- **id** - MongoDB ObjectId of the smart match

## Response Body

```json
{
  "message": "smart match accepted"
}
```

# 🔒 POST `/smart-matches/:id/feedback`

## Description

- Submits feedback for an accepted smart match
- The authenticated user must be either `userA` or `userB` of that match
- Smart match must be `accepted`
- Sets the user's `feedback` and `feedbackAt` to now
- Updates `user.smartMatch.weights[dominant]` by `+0.1` (good/ok) or `-0.1` (bad), where `dominant` is whichever of `energy`, `values`, `activity`, `intent` scored highest in the match
- Deletes the `smart-match-feedback` notification for this user and smart match
- Creates a new `smart-match-feedback-submitted` notification for this user
- Returns `404` if not found, user doesn't belong to the match, or match is not `accepted`
- Returns `409` if the user has already submitted feedback

## Request Params

- **id** - MongoDB ObjectId of the smart match

## Request Body

- **feedback** - required; one of `good`, `ok`, `bad`

## Response Body

```json
{
  "message": "feedback submitted"
}
```

# 🔒 POST `/smart-matches/:id/reject`

## Description

- Rejects a smart match
- The authenticated user must be either `userA` or `userB` of that match
- Smart match must be `pending`
- Sets the user's `response` to `no` and `responseAt` to now
- Sets `status` to `declined` and `declinedAt` to now
- Socket notifies both users with event `smart-match-declined`
- Returns `404` if not found, user doesn't belong to the match, or match is not `pending`

## Request Params

- **id** - MongoDB ObjectId of the smart match

## Response Body

```json
{
  "message": "smart match rejected"
}
```

# 🌍 POST `/smart-matches/create-smart-matches` (Testing Only)

## Description

- **PUBLIC endpoint - for testing only**
- Triggers the smart match creation and suggestion jobs manually
- Creates new smart match documents for all eligible user pairs in their communities
- Then suggests pending smart matches to users based on their limits and constraints
- Returns immediately after queueing both jobs in the background

## Response Body

```json
{
  "message": "done"
}
```

# Links

[Goto Home](/docs/index.html)