# Event Management

### Overview

The SDK supports two primary event types:

* Normal Events: Standard quest-based events focusing on task completion
* Score-Based Events: Competitive events with point-based leaderboards

### Normal Events

Normal Events are standard events where users can complete one or more quests to earn rewards. These events do not track a cumulative score for participants but focus on task completion.

#### Type Definition

```typescript
type NormalEvent = BasicEventType & {
  type: QUEST_EVENT_TYPE.BASIC; // 1
  quests: QuestDetailsType[];
};
```

### Score-Based Events

Score-Based Events involve quests where participants earn points to compete on a leaderboard. These events are commonly used for competitive scenarios where scoring determines ranking or rewards.

#### Type Definition

```typescript
type ScoreBasedEvent = BasicEventType & {
  type: QUEST_EVENT_TYPE.SCORE; // 2
  quests: ScoreQuest[];
};
```

The `type` field identifies the event as a SCORE quest event, while the `quests` array contains `ScoreQuest` objects that define tasks contributing to the participant's total score.

### Event Data Structure

All event types inherit from the `BasicEventType`, which provides the foundation for handling event data in the UI. This includes essential information like dates, participation status, requirements, and rewards.

#### Type Definition

```typescript
type BasicEventType = {
  containerId: string;                // ID of the container or community hosting the event
  createdAt: FlexDate;               // Timestamp for when the event was created
  createdBy: string;                 // Creator of the event
  description: string | ParsableContent[]; // Description of the event
  summary?: string | ParsableContent[]; // Shorter description for main event view
  endDate: FlexDate;                 // Date when the event ends
  eventId: string;                   // Unique identifier for the event
  maxParticipants: number;           // Maximum number of participants allowed
  registrationEndDate: FlexDate;     // End date for registrations
  registrationStartDate: FlexDate;   // Start date for registrations
  startDate: FlexDate;               // Date when the event begins
  title: string;                     // Event title
  totalParticipants: number;         // Total number of current participants
  updatedAt: FlexDate;               // Timestamp for the last update to the event
  updatedBy: string;                 // User who last updated the event
  rewards?: EventRewardType[];       // Optional array of rewards for the event
  status: QUEST_EVENT_STATUS;        // Current status of the event
  slug: string;                      // Slug for URL or identification
  participation?: {                  // Participant-specific details
    isParticipating: boolean;        // Whether the current user is participating
    status: string;                  // Participant's current status in the event
    syncStatus: ParticipantSyncStatusType; // Backend sync status for the participant
  };
  requirements?: Array<EventRequirementType>; // Optional array of requirements for joining the event
  images?: {                         // Optional image assets
    coverImageUrl: string;           // URL for the event's cover image
    displayImageUrl?: string;        // A secondary image
    iconImageUrl?: string;           // Icon for event
  };
};
```

### Key Fields Explained

#### General Information

* `containerId`: Identifies the hosting community or group
* `title`: The name of the event
* `description`: Detailed information about the event, either as plain text or parsed content

#### Timelines

* `startDate` and `endDate`: Define the active period of the event
* `registrationStartDate` and `registrationEndDate`: Define when users can register for the event

#### Participants and Capacity

* `maxParticipants`: Maximum number of users allowed to join
* `totalParticipants`: Current number of registered users

#### Rewards

* `rewards`: Defines the rewards available for participating or completing quests in the event

#### Participation Details

* `participation`: Includes fields to track whether the current user is participating, their status, and the synchronization status with the backend

#### Requirements

* `requirements`: Specifies any conditions that users must meet to join the event (e.g., completed quests or prior achievements)

#### Visuals

* `images`: Contains optional media assets such as a cover image for the event

#### Metadata

* `createdAt`, `createdBy`, `updatedAt`, `updatedBy`: Provide audit information about the event's creation and last modification

### Deep Dive: BasicEventType Options

#### Status

The `status` field of `BasicEventType` reflects the current state of the event. Common statuses include:

* `DRAFT`: The event has been created but isn't published yet (not visible in community UI)
* `PUBLISHED`: The event has been created and is visible in the UI
* `RESOLVING`: The event is currently active
* `COMPLETED`: The event has concluded
* `CANCELLED`: The event has been canceled

#### Rewards

The `rewards` field is an optional array of rewards associated with the event:

```typescript
type EventRewardType = {
  eventRewardId: string;
  name: string;
  resolutionType: QuestEventRewardResolutionType;
  resolutionValueRange: ResolutionValueType;
  rewardId: string;
  reward: EventGiveResourcesReward | EventGiveAssetsReward;
  rewardHandlerArgs: EventGiveResourcesRewardHandler | EventGiveAssetsRewardHandler;
  eventId: string;
  createdAt: Date;
  updatedAt: Date;
};
```

#### Participation

The `participation` object tracks the user's involvement in the event. Example usage:

```typescript
{
  isParticipating: true,               // User has joined the event
  status: "COMPLETED",                 // User's progress (e.g., "IN_PROGRESS", "COMPLETED")
  syncStatus: "SYNCED",                // Sync status of participation
}
```

#### Requirements

The `requirements` field defines prerequisites for event participation. Example:

```typescript
requirements: [
  {
    name: 'quest_completed',
    requirementId: "quest-123",
    requirementArgs: {
      outcome: 1,
      questId: "quest-1234"
    },
    data: {
      id: "abc",
      title: "Some quest"
    }
  }
];
```