Skip to main content

​
Marketplace API

The Marketplace API provides client-side functions for interacting with the BuildAppsWith marketplace, including fetching builder profiles, marketplace filter options, and builder analytics.

​
Core Features

  • Builder Discovery: Search and filter for builders based on skills, validation tier, and availability
  • Builder Profiles: Fetch detailed information about specific builders
  • Analytics: Access analytics data for builder dashboards
  • Filtering: Retrieve available filter options for marketplace search

​
API Reference

​
Builders

​
fetchBuilders
function
Fetch builders from the API with pagination and filtering
async function fetchBuilders(
  page: number = 1, 
  limit: number = 9,
  filters?: MarketplaceFilters
): Promise<BuildersResponse>
​
fetchBuilderById
function
Fetch a single builder by ID
async function fetchBuilderById(
  builderId: string
): Promise<BuilderProfileData | null>
​
fetchFeaturedBuilders
function
Fetch featured builders
async function fetchFeaturedBuilders(
  limit: number = 3
): Promise<BuilderProfileListing[]>

​
Filters

​
fetchMarketplaceFilterOptions
function
Fetch available marketplace filter options
async function fetchMarketplaceFilterOptions(): Promise<MarketplaceFilterOptions>

​
Analytics

​
fetchBuilderAnalyticsSummary
function
Fetch analytics summary for builder dashboard
async function fetchBuilderAnalyticsSummary(
  period: number = 30
): Promise<AnalyticsSummary>
​
fetchBuilderAnalyticsTimeseries
function
Fetch analytics timeseries for builder dashboard
async function fetchBuilderAnalyticsTimeseries(
  period: number = 30
): Promise<AnalyticsTimeseries>
​
fetchBuilderSuccessMetrics
function
Fetch success metrics for builder dashboard
async function fetchBuilderSuccessMetrics(): Promise<SuccessMetrics>

​
Component Usage

​
Using the Consolidated Builder Image Component

import { BuilderImage } from '@/components/marketplace/components/builder-image';

function BuilderProfile({ builder }) {
  return (
    <div className="profile-container">
      <BuilderImage 
        src={builder.avatarUrl}
        alt={builder.name}
        size="lg"
      />
      <h2>{builder.name}</h2>
    </div>
  );
}

​
BuilderImage Component API

​
BuilderImage
component
A unified component for displaying builder profile images with proper fallback handling and error states.
import { BuilderImage } from '@/components/marketplace/components/builder-image';

​
Error Handling Strategy

The consolidated BuilderImage component handles several error conditions:

​
Missing or Null Image Source

  • When src is null, undefined, or an empty string
  • Component automatically displays the ImageFallback with the first letter of the alt text
  • No error messages are displayed to the user

​
Invalid Image URL Format

  • Validation check prevents loading non-URL strings
  • If validation fails, component displays the fallback
  • Prevents unnecessary network requests for invalid URLs

​
Image Loading Failures

  • When the image URL is valid but fails to load (404, CORS issues, etc.)
  • Uses Next.js Image onError handler to hide the broken image
  • Automatically reveals the underlying fallback element
  • User sees a seamless transition to the fallback

​
Example Usage with Error Handling

<BuilderImage 
  src={builder.avatarUrl} // May be null/undefined
  alt={builder.name}      // Used for both alt text and fallback
  size="md"               // Handles invalid sizes gracefully
  className="my-custom-class" // Optional styling
/>

​
Usage Examples

​
Fetching Builders with Filters

import { fetchBuilders, MarketplaceFilters } from '@/lib/marketplace';

async function loadBuildersList() {
  // Type safety with consolidated types
  const filters: MarketplaceFilters = {
    searchQuery: 'react',
    skills: ['javascript', 'react', 'typescript'],
    validationTiers: [2, 3], // Established and Expert
    availability: ['available'],
    sortBy: 'rating'
  };

  try {
    const result = await fetchBuilders(1, 12, filters);
    return result.data; // Array of builder profiles
  } catch (error) {
    console.error('Failed to load builders:', error);
    return [];
  }
}

​
Fetching a Builder Profile

import { fetchBuilderById } from '@/lib/marketplace';

async function loadBuilderProfile(id: string) {
  try {
    const builder = await fetchBuilderById(id);
    if (!builder) {
      throw new Error('Builder not found');
    }
    return builder;
  } catch (error) {
    console.error(`Failed to load builder ${id}:`, error);
    return null;
  }
}

​
Accessing Builder Analytics

import { 
  fetchBuilderAnalyticsSummary, 
  fetchBuilderAnalyticsTimeseries 
} from '@/lib/marketplace';

async function loadDashboardData() {
  try {
    // For the last 7 days
    const summary = await fetchBuilderAnalyticsSummary(7);
    const timeseries = await fetchBuilderAnalyticsTimeseries(7);
    
    return {
      summary,
      timeseries
    };
  } catch (error) {
    console.error('Failed to load dashboard data:', error);
    return null;
  }
}