Getting Started

Installation

npm i @remcostoeten/fync

Quick Setup

import { GitHub, Spotify, GoogleCalendar } from '@remcostoeten/fync';

const github = GitHub({ token: process.env.GITHUB_TOKEN! });
const spotify = Spotify({ token: process.env.SPOTIFY_TOKEN! });
const calendar = GoogleCalendar({ token: process.env.GOOGLE_TOKEN! });

First API Calls

// GitHub
const user = await github.getUser('octocat');
const repo = await github.getRepository('facebook', 'react');

// Spotify
const playlist = await spotify.getPlaylist('37i9dQZF1DXcBWIGoYBM5M');
const currentlyPlaying = await spotify.getCurrentlyPlaying();

// Google Calendar
const events = await calendar.getUpcomingEvents('primary', 10);
const todaysEvents = await calendar.getTodaysEvents();

How It Works

Resources & Methods

Every provider has resources (like users, repos, playlists) with methods:

// Resource-based calls
const user = await github.users.getUser({ username: 'octocat' });
const playlist = await spotify.playlists.getPlaylist({ playlist_id: 'abc' });

// Or use the convenient helper methods
const user = await github.getUser('octocat');
const playlist = await spotify.getPlaylist('abc');

Method Patterns

With data (POST/PUT/PATCH):

// Method signature: (data, options)
await calendar.createEvent(
  { summary: 'Meeting', start: { dateTime: '2024-01-01T10:00:00Z' } },
  { calendarId: 'primary' }
);

// Helper version:
await calendar.createEvent('primary', { summary: 'Meeting' });

Without data (GET/DELETE):

// Method signature: (options)
await github.repos.getRepo({ owner: 'facebook', repo: 'react' });

// Helper version:
await github.getRepository('facebook', 'react');

Path Parameters & Query Params

Path placeholders are filled automatically, everything else becomes query params:

// {owner} and {repo} fill the path, per_page becomes a query param
const commits = await github.repos.getRepoCommits({
  owner: 'facebook',
  repo: 'react',
  per_page: 50
});

Authentication

Most services use bearer tokens. Get them from the respective developer consoles:

GitHub: Settings → Developer settings → Personal access tokens
Spotify: Spotify Developer Dashboard → Create App → Get Token
Google Calendar: Google Cloud Console → Enable API → Create Credentials

Error Handling

Wrap calls in try/catch - the client throws on non-2xx responses:

try {
  const user = await github.getUser('octocat');
  console.log('User:', user);
} catch (error) {
  console.error('API Error:', error.message);
}

Next Steps

Check Provider Guides for detailed method references
See Core Concepts for advanced patterns
Browse Examples for common use cases

Getting Started

On this page