🧭 About

FedSync Standalone is a TypeScript CLI and library for syncing Federator API data into organized local JSON files. It is built for teams that need reliable local access to profiles, events, categories, and amenities for static builds, app hydration, or downstream processing.

The project stays focused on one job: syncing data accurately, quickly, and with enough operational guardrails to recover from interruptions without adding unnecessary complexity.

✨ Features

| Feature | Description | |---------|-------------| | 🚀 Unified Sync | Processes profiles and events in a single API pass, cutting duplicate work and reducing API traffic. | | ♻️ Auto-Resume | Saves checkpoint state so interrupted syncs can continue from the last successful page. | | 🗂 JSON-First Output | Writes clean, organized JSON files that are easy to inspect, cache, and consume from app code. | | 🌊 Streaming Mode | Emits JSONL to stdout for containers, CI jobs, and other ephemeral environments. | | 🧩 Type-Safe Surface | Exposes generated API types, a typed client, and hydration helpers for application code. | | 🔒 Defensive Defaults | Includes token validation, path traversal protection, retry handling, and input sanitization. |

🛠 Built With

🚀 Getting Started

Prerequisites

• Node.js 20 or higher
• pnpm
• Federator API credentials

Installation

git clone https://github.com/erawk26/fedsync.git
cd fedsync
pnpm install

Configuration

Create a .env file in the project root:

FEDERATOR_BEARER_TOKEN=your_token_here
FEDERATOR_API_URL=https://your.federator.milespartnership.com/api/federator
OUTPUT_DIR=./output
LOG_LEVEL=2

Usage

# Default sync: profiles + events + reference data
pnpm exec fedsync

# Full sync including archive and cleanup
pnpm exec fedsync --all

Programmatic Example

import { ListingHydrator } from 'fedsync-standalone';

const hydrator = new ListingHydrator('./output');
const profiles = await hydrator.getAllProfiles();
const events = await hydrator.getAllEvents();

⚙️ Common Commands

# Sync only profiles
pnpm exec fedsync --profiles-only

# Sync only events
pnpm exec fedsync --events-only

# Sync reference data only
pnpm exec fedsync --reference-only

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

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

# Archive inactive nodes
pnpm exec fedsync --inactive-only

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

🌊 Streaming Mode

Streaming mode is designed for environments where writing sync output to disk is a poor fit, such as containers, short-lived CI jobs, and pipe-based data workflows.

# Stream all supported entity types as JSONL
pnpm exec fedsync --output=stream

# Stream selected entities
pnpm exec fedsync --output=stream --entity-types=profiles,events

# Delta stream since a specific date
pnpm exec fedsync --output=stream --since=2024-01-01

# Pipe streamed output to another tool
pnpm exec fedsync --output=stream --entity-types=profiles | jq '.name'

Supported stream entity types:

• profiles
• events
• categories
• amenities

📁 Project Structure

fedsync/
├── src/                # Core TypeScript source
├── tests/              # Unit, integration, and streaming tests
├── docs/               # User and architecture documentation
├── examples/           # Framework integration examples
├── scripts/            # OpenAPI and type-generation utilities
├── openapi.json        # Federator API specification input
└── output/             # Default sync output directory

📦 Output Shape

output/
├── profiles/
├── events/
├── categories/
├── amenities/
├── archive/
│   ├── profiles/
│   └── events/
└── .sync/

⚡ Performance

FedSync is optimized around practical sync throughput rather than abstraction layers.

• Unified sync processes profiles and events in one pass.
• Pagination defaults are tuned for the Federator API.
• Checkpointing reduces wasted work after failures or rate limits.
• Typical runs handle roughly 1,500 items in about 35 seconds.

🧪 Development

# Build the project
pnpm run build

# Run the full test suite
pnpm test

# Generate OpenAPI-based types
pnpm run generate-types

# Run coverage
pnpm run test:coverage

📚 Documentation

• Getting Started
• CLI Reference
• Architecture Guide
• Logging Guide
• Security Guide
• OpenAPI Integration
• Type Generation Guide
• Performance Tuning
• Examples
• Troubleshooting

🤝 Contributing

Pull requests are welcome. Keep changes aligned with the project’s core goal: reliable, secure, and efficient Federator data syncing. If you change sync behavior, CLI flags, or exposed types, update the corresponding docs and examples in the same pass.

📄 License

GPL-3.0. See LICENSE for the full text.