Working with Events

Overview

The shared package provides two primary event types:

• Normal Events

• Score-Based Events

While both types share the same core data structure and fetching mechanisms, they differ in quest structure. A third type (Collaborative Events) will be available soon via the SDK.

Fetching Events

1. Using the useCommunityEvents Hook

The simplest way to fetch events is using the useCommunityEvents hook:

"use client";
import { useCommunityEvents } from "@xborglabs/ui-shared/dist/client";

export function EventsContainer() {
  const { data: events, status } = useCommunityEvents(clientEnv.NEXT_PUBLIC_COMMUNITY_ID);

  if (status === "pending") {
    return <p>Loading events...</p>;
  }

  if (status === "error") {
    return <p>An error occurred...</p>;
  }

  return (
    <div>
      {events?.map((event) => (
        <div key={event.eventId}>
          <h3>{event.title}</h3>
          <p>Event Type: {event.eventType}</p>
        </div>
      ))}
    </div>
  );
}

Key Points:

• Uses NEXT_PUBLIC_COMMUNITY_ID environment variable to fetch community-specific events

• Returns data (event array) and status (pending, success, or error)

• Requires handling of loading and error states

2. Using Headless Components

The shared package provides several headless components for event management:

Community Event List

import { CommunityEventList, CommunityEventTag } from "@xborglabs/ui-shared/dist/client";

<CommunityEventList communityId={communityId as string} tags={tags as CommunityEventTag[]}>
  {({ events, status, availableTags, offset, total }) => (
    <>
      {/* Render your event list */}
    </>
  )}
</CommunityEventList>

Featured Event List

import { FeaturedEventsList } from "@xborglabs/ui-shared/dist/client";

export default function App() {
  return (
    <FeaturedEventsList>
      {({ events }) => (
        <>
          {/* Render featured events */}
        </>
      )}
    </FeaturedEventsList>
  );
}

Event Details

import { EventDetail } from "@xborglabs/ui-shared/dist/client";

<EventDetail eventId={event.eventId} filter={filter}>
  {({ event, refetch, joinStates, questStatus }) => (
    <>
      {/* Render event details */}
    </>
  )}
</EventDetail>

Event Rank

import { EventRank } from "@xborglabs/ui-shared";

export default function App() {
  return (
    <EventRank event={event}>
      {({ balance, rank }) => (
        <>
          {/* Render user rank */}
        </>
      )}
    </EventRank>
  );
}

3. Using Base API Functions

For advanced scenarios or server-side logic, use these base functions:

// Fetch paginated featured events
function getFeaturedEvents(api: AxiosInstance);

// Fetch community-specific events
function getCommunityEvents(api: AxiosInstance, id: string);

Working with Event Data

Rendering Event Details

Both event types share a core data structure. Here's how to render event-specific details:

function EventDetails({ event }: { event: Event }) {
  const { eventId, title, eventType, score, quest } = event;

  return (
    <div key={eventId}>
      <h3>{title}</h3>
      <p>Type: {eventType === 1 ? "Normal Event" : "Score-Based Event"}</p>

      {eventType === 2 && <p>Score: {score || "No score available"}</p>}

      {eventType === 1 && (
        <div>
          <h4>Quests</h4>
          <ul>
            {quest?.map((q) => (
              <li key={q.id}>{q.description}</li>
            )) || <p>No quests available</p>}
          </ul>
        </div>
      )}
    </div>
  );
}

API Methods

Core methods for event management:

// Fetch paginated featured events
function getFeaturedEvents(api: AxiosInstance);

// Fetch events for a specific community
function getCommunityEvents(api: AxiosInstance, id: string);

// Get user rank information
function getEventUserRank(api: AxiosInstance, eventId: string);

// Get event leaderboard (paginated)
function getQuestEventLeaderBoard(api: AxiosInstance, eventId: string, page: number, limit: number);

// Join an event
function postParticipateEvent(api: AxiosInstance, eventId: string);

// Leave an event
function putLeaveEvent(api: AxiosInstance, eventId: string);

Best Practices

Type Checking

Use TypeScript for type safety:

type Event = {
  eventId: string;
  title: string;
  eventType: 1 | 2;
  score?: number;
  quest?: Array<SingleQuestDetail>;
};

Implementation Guidelines

1. Fallbacks: Always provide fallback UI for missing data

2. Dynamic Rendering: Use conditional rendering for different event types

3. Testing: Test all states (loading, error, success)

Advanced Topics

1. Extending Event Types

When adding new event types, ensure backward compatibility by:

• Adding new eventType values

• Updating component handling logic

2. Custom Hooks

Create custom hooks for specific use cases:

function useFilteredEvents(events: Event[], type: "normal" | "score") {
  return events.filter((event) => event.eventType === type);
}

3. Backend Integration

• Stay updated with SDK and Swagger documentation changes

• Coordinate with backend teams on new error codes or fields