-
Notifications
You must be signed in to change notification settings - Fork 0
API Reference
Complete reference for all JavaScript functions in SideQuest.
Main application orchestrator.
Initializes the SideQuest application.
Description: Entry point that sets up auth listeners, UI event handlers, and initializes the app.
Parameters: None
Returns: void
Example:
init();Implementation:
- Sets up auth state listener
- Displays loading screen
- Routes to auth or app page based on login state
- Initializes map and task listeners when authenticated
Displays the authentication page.
Description: Hides the app page and shows the login/signup interface.
Parameters: None
Returns: void
Example:
showAuth();Displays the main application interface.
Description: Hides auth page, shows the map and app interface for authenticated users.
Parameters:
-
user(Object): Firebase user object
Returns: void
Example:
onAuthStateChanged(auth, (user) => {
if (user) {
showApp(user);
}
});Authentication module.
Sets up authentication UI and event listeners.
Description: Initializes form submissions, toggles, and error displays.
Parameters: None
Returns: void
Example:
initializeAuth();Authenticates an existing user.
Description: Signs in user with email and password using Firebase Auth.
Parameters:
-
email(string): User's email address -
password(string): User's password
Returns: Promise<UserCredential>
Throws: FirebaseError if authentication fails
Example:
try {
await handleLogin('user@example.com', 'password123');
console.log('Login successful');
} catch (error) {
console.error('Login failed:', error);
}Creates a new user account.
Description: Creates a new user with email and password, then updates their profile with display name.
Parameters:
-
name(string): User's display name -
email(string): User's email address -
password(string): User's password (min 6 characters)
Returns: Promise<void>
Throws: FirebaseError if signup fails
Example:
try {
await handleSignup('John Doe', 'john@example.com', 'password123');
console.log('Account created');
} catch (error) {
console.error('Signup failed:', error);
}Signs out the current user.
Description: Signs out the user and redirects to auth page.
Parameters: None
Returns: Promise<void>
Example:
await logout();Displays an authentication error message.
Description: Shows error message to user in auth error element.
Parameters:
-
message(string): Error message to display
Returns: void
Example:
showError('Invalid email or password');Map rendering and interaction module.
Initializes the MapLibre GL map.
Description: Creates map instance, centers on user location (or default), adds controls and user marker.
Parameters:
-
user(Object): Firebase user object
Returns: maplibregl.Map - Map instance
Example:
const map = initMap(currentUser);Adds a marker for the user's current location.
Description: Creates a blue marker at user's coordinates.
Parameters:
-
lng(number): Longitude -
lat(number): Latitude
Returns: maplibregl.Marker - User marker instance
Example:
const marker = addUserMarker(72.8777, 19.0760);Updates the user's location marker.
Description: Moves existing user marker to new coordinates.
Parameters:
-
lng(number): New longitude -
lat(number): New latitude
Returns: void
Example:
navigator.geolocation.watchPosition((position) => {
updateUserMarker(position.coords.longitude, position.coords.latitude);
});Adds a task marker to the map.
Description: Creates a colored marker for a task with click handler.
Parameters:
-
task(Object): Task data object-
id(string): Task ID -
location(Object): {lat, lng} -
category(string): Task category -
title(string): Task title
-
-
onClick(Function): Callback when marker is clicked
Returns: maplibregl.Marker - Task marker instance
Example:
addMarker(task, (taskData) => {
openTaskDetail(taskData);
});Removes all task markers from the map.
Description: Iterates through markers Map and removes each marker.
Parameters: None
Returns: void
Example:
clearMarkers();
// Then add new markersCalculates distance between two coordinates using Haversine formula.
Description: Returns distance in kilometers.
Parameters:
-
coord1(Object): {lat, lng} -
coord2(Object): {lat, lng}
Returns: number - Distance in kilometers
Example:
const distance = calculateDistance(
{ lat: 19.0760, lng: 72.8777 },
{ lat: 19.0800, lng: 72.8800 }
);
console.log(`${distance.toFixed(2)} km away`);Smoothly animates map to user's current location.
Description: Flies to user marker position with animation.
Parameters: None
Returns: void
Example:
locateButton.addEventListener('click', flyToUserLocation);Gets the current center coordinates of the map.
Description: Returns the map center as {lng, lat}.
Parameters: None
Returns: Object - {lng: number, lat: number}
Example:
const center = getMapCenter();
console.log(`Map centered at ${center.lat}, ${center.lng}`);Sets up geolocation watcher.
Description: Watches user location and calls callback on updates.
Parameters:
-
callback(Function): Called with (lng, lat) on location change
Returns: number - Watch ID for clearing
Example:
const watchId = onUserLocationUpdate((lng, lat) => {
updateUserMarker(lng, lat);
});
// Later: navigator.geolocation.clearWatch(watchId);Task management and CRUD operations.
Sets up all task-related UI event listeners.
Description: Attaches click handlers for modals, forms, navigation, etc.
Parameters: None
Returns: void
Example:
initTaskListeners();Opens the task creation modal.
Description: Shows modal with slide-up animation.
Parameters: None
Returns: void
Example:
fabButton.addEventListener('click', openCreateModal);Closes all open modals.
Description: Hides and resets all modal elements.
Parameters: None
Returns: void
Example:
cancelButton.addEventListener('click', closeModals);Creates a new task in Firestore.
Description: Validates input, handles escrow if reward offered, creates task document.
Parameters:
-
data(Object): Task data-
title(string): Task title -
description(string): Task description -
category(string): Task category -
reward(number): Reward amount (optional) -
location(Object): {lat, lng}
-
Returns: Promise<string> - Created task ID
Throws: Error if validation fails or insufficient balance
Example:
try {
const taskId = await createTask({
title: 'Walk my dog',
description: 'Need help walking my golden retriever',
category: 'Help',
reward: 50,
location: getMapCenter()
});
console.log('Task created:', taskId);
} catch (error) {
showToast(error.message, 'error');
}Sets up real-time listener for tasks collection.
Description: Listens to open tasks and updates map markers.
Parameters: None
Returns: Function - Unsubscribe function
Example:
const unsubscribe = listenForTasks();
// Later: unsubscribe();Sets up real-time listener for user document.
Description: Listens to user profile and wallet updates.
Parameters:
-
uid(string): User ID to listen to
Returns: Function - Unsubscribe function
Example:
const unsubscribe = listenToUser(auth.currentUser.uid);Claims an open task for a user.
Description: Updates task status to 'in-progress' and assigns to user.
Parameters:
-
taskId(string): Task document ID -
userId(string): Claiming user's ID
Returns: Promise<void>
Throws: Error if task is not open or user is the poster
Example:
try {
await claimTask('task123', auth.currentUser.uid);
showToast('Task claimed!', 'success');
} catch (error) {
showToast(error.message, 'error');
}Marks a task as completed with a rating.
Description: Updates task status, transfers reward, updates ratings.
Parameters:
-
taskId(string): Task document ID -
rating(number): Rating from 1-5 stars
Returns: Promise<void>
Throws: Error if transaction fails
Example:
await completeTask('task123', 5);
showToast('Task completed! Payment released.', 'success');Deletes a task and refunds escrow.
Description: Only poster can delete. Refunds reward if held in escrow.
Parameters:
-
taskId(string): Task document ID
Returns: Promise<void>
Throws: Error if user is not poster or task is claimed
Example:
try {
await deleteTask('task123');
showToast('Task deleted', 'success');
} catch (error) {
showToast('Cannot delete claimed task', 'error');
}Opens task detail modal with task information.
Description: Populates modal with task data and shows it.
Parameters:
-
task(Object): Complete task data object
Returns: void
Example:
addMarker(task, (taskData) => {
openTaskDetail(taskData);
});Processes Firestore snapshot updates.
Description: Updates map markers based on snapshot changes.
Parameters:
-
snapshot(QuerySnapshot): Firestore query snapshot
Returns: void
Example:
onSnapshot(tasksQuery, handleSnapshot);UI utilities and helper functions.
Displays a toast notification.
Description: Shows temporary notification at top of screen.
Parameters:
-
message(string): Message to display -
type(string): 'success' | 'error' | 'info' | 'warning'
Returns: void
Example:
showToast('Task created successfully!', 'success');
showToast('Something went wrong', 'error');Shows a confirmation dialog.
Description: Displays modal asking user to confirm action.
Parameters:
-
title(string): Dialog title -
message(string): Confirmation message
Returns: Promise<boolean> - true if confirmed, false if cancelled
Example:
const confirmed = await showConfirm(
'Delete Task',
'Are you sure you want to delete this task?'
);
if (confirmed) {
await deleteTask(taskId);
}Opens a modal with animation.
Description: Shows modal with fade-in/slide-up animation.
Parameters:
-
modalElement(HTMLElement): Modal element to open
Returns: void
Example:
const modal = document.getElementById('create-modal');
openModal(modal);Closes a modal with animation.
Description: Hides modal with fade-out/slide-down animation.
Parameters:
-
modalElement(HTMLElement): Modal element to close
Returns: void
Example:
closeModal(createModal);Formats timestamp as relative time.
Description: Converts Firestore timestamp to "2 mins ago", "1 hour ago", etc.
Parameters:
-
timestamp(Timestamp): Firestore timestamp
Returns: string - Formatted relative time
Example:
const timeAgo = formatRelativeTime(task.createdAt);
// "5 minutes ago"Formats number as currency.
Description: Formats number with rupee symbol and proper decimals.
Parameters:
-
amount(number): Amount in rupees
Returns: string - Formatted currency string
Example:
const formatted = formatCurrency(1500);
// "₹1,500"Firebase initialization and configuration.
Type: Auth
Description: Firebase Authentication instance
Usage:
import { auth } from './firebase-config.js';
import { signInWithEmailAndPassword } from 'firebase/auth';
await signInWithEmailAndPassword(auth, email, password);Type: Firestore
Description: Firestore database instance
Usage:
import { db } from './firebase-config.js';
import { collection, getDocs } from 'firebase/firestore';
const snapshot = await getDocs(collection(db, 'tasks'));interface Task {
id: string;
title: string;
description: string;
category: 'Help' | 'Delivery' | 'Social' | 'Other';
reward: number;
escrowHeld: boolean;
status: 'open' | 'in-progress' | 'completed';
location: {
lat: number;
lng: number;
};
postedBy: string;
postedByName: string;
claimedBy: string | null;
claimedByName: string | null;
rated: boolean;
rating: number | null;
createdAt: Timestamp;
claimedAt: Timestamp | null;
completedAt: Timestamp | null;
}interface User {
uid: string;
name: string;
email: string;
wallet: number;
tasksCompleted: number;
tasksPosted: number;
totalRating: number;
ratingCount: number;
createdAt: Timestamp;
lastActive: Timestamp;
}All async functions should be wrapped in try-catch:
try {
await createTask(taskData);
showToast('Success!', 'success');
} catch (error) {
console.error('Error:', error);
showToast(error.message, 'error');
}- Always validate input before database operations
- Use transactions for wallet operations
- Detach listeners when no longer needed
- Handle errors gracefully with user-friendly messages
- Log errors to console for debugging