FedSync Standalone

🚀 Quick Start | 🔧 CLI Reference | 🎯 Examples | 📝 Logging | 🔒 Security | 🔗 OpenAPI Integration | ⚙️ Type Customization | ⚡ Performance

A fast, simple TypeScript CLI tool for syncing Federator API data as organized JSON files. Perfect for JAMstack sites, Next.js apps, or any application that needs fast, local access to Federator data.

✨ Highlights

• Unified Sync: Processes profiles and events in a single API pass (50% fewer API calls!)
• Auto-Resume: Automatically resumes from interruptions
• Clean & Simple: No complex abstractions - just fast, reliable syncing
• Type-Safe: Full TypeScript support with generated types from OpenAPI spec

⚡ Quick Start

# Install
pnpm install fedsync-standalone

# Configure (create .env file)
echo "FEDERATOR_BEARER_TOKEN=your_token_here" > .env
echo "FEDERATOR_API_URL=your_api_url_here" >> .env

# Sync all data (profiles + events in ONE pass!)
pnpm exec fedsync

# Use in your app
import { ListingHydrator } from 'fedsync-standalone';
const hydrator = new ListingHydrator();
const profiles = await hydrator.getAllProfiles();

New to FedSync? → Complete setup guide

Installation

pnpm install fedsync-standalone

Node Version

This project requires Node.js 20 or higher. Use nvm to switch to the correct version:

nvm use

Environment Setup

Create a .env file or set environment variables:

FEDERATOR_BEARER_TOKEN=your_token_here
FEDERATOR_API_URL=https://your.federator.milespartnership.com/api/federator
OUTPUT_DIR=./output  # Optional, defaults to ./output

CLI Usage

Default sync (profiles + events + reference data)

pnpm exec fedsync

This efficiently syncs:

• Profiles and events in a single pass through the API
• Categories and amenities reference data
• Performs cleanup of stale files

Sync everything including archive and cleanup

pnpm exec fedsync --all

Selective sync options

# Sync only profiles (still uses unified sync internally)
pnpm exec fedsync --profiles-only

# Sync only events (still uses unified sync internally)
pnpm exec fedsync --events-only

# Sync only reference data (categories + amenities)
pnpm exec fedsync --reference-only

# Sync only categories
pnpm exec fedsync --categories-only

# Sync only amenities
pnpm exec fedsync --amenities-only

# Sync inactive/archived nodes
pnpm exec fedsync --inactive-only

# Run cleanup operations only
pnpm exec fedsync --cleanup-only

Generate types from OpenAPI specification

# Generate types from real API
pnpm run generate-types

# Use hybrid types for full type safety
import type { EnhancedPaths, APIResponse } from 'fedsync-standalone/api-types';

⚠️ Important: The API's OpenAPI spec only defines endpoints and parameters, not response data models. See Type Customization Guide for details on what gets auto-generated vs. what you need to customize manually.

Output Structure

output/
├── profiles/          # Individual profile JSON files
├── events/           # Individual event JSON files  
├── categories/       # Categories reference data
├── amenities/        # Amenities reference data
├── archive/          # Archived (inactive) data
│   ├── profiles/
│   └── events/
└── .sync/            # Sync state and checkpoints

🚀 Performance

FedSync is optimized for speed and efficiency:

• Unified sync: Processes both profiles and events in one API pass (50% reduction in API calls)
• Smart pagination: Uses 40 items per page for optimal performance
• Auto-resume: Saves progress and resumes from interruptions
• Efficient storage: Each item saved as individual JSON file for fast access

Typical sync performance:

• ~1,500 profiles + events in ~35 seconds
• ~43 items/second throughput
• Automatic rate limit handling

🛠️ Programmatic Usage

import { ListingHydrator } from 'fedsync-standalone';

// Initialize hydrator
const hydrator = new ListingHydrator('./output');

// Get all profiles
const profiles = await hydrator.getAllProfiles();

// Get a specific profile
const profile = await hydrator.getProfile('listing-123');

// Get all events
const events = await hydrator.getAllEvents();

// Get profiles and events for a specific profile
const enriched = await hydrator.getEnrichedProfile('listing-123');

📚 Documentation

• Getting Started Guide - Complete setup walkthrough
• CLI Reference - All command options
• Architecture Guide - How FedSync works
• Examples - Next.js, React Query, and more
• Troubleshooting - Common issues and solutions

🔒 Security

FedSync includes built-in security features:

• Bearer token validation
• Path traversal protection
• Rate limiting
• Input sanitization

See Security Guide for details.

📄 License

MIT License - see LICENSE file for details.