@remcostoeten/fync

Installation

bun add @remcostoeten/fync

Development

Setup

# Install dependencies for all workspaces
bun install
# Build the library
bun run build
# Run tests
bun run test
# Start development mode (watch for changes)
bun run dev

Project Structure

fync/
├── README.md # This file
├── LICENSE
├── package.json # Workspace root
├── bun.lock
├── .npmrc
└── apps/
 ├── fync/ # Main @remcostoeten/fync package
 │ ├── src/ # TypeScript source code
 │ ├── dist/ # Compiled output
 │ └── package.json
 └── examples/ # Usage examples
 ├── oauth-drizzle-nextjs.ts
 ├── oauth-simple-usage.ts
 └── unified-usage.ts

Usage

Spotify API

import { Spotify } from '@remcostoeten/fync/spotify'
// Use environment variables for security
const spotify = Spotify({
 token: process.env.SPOTIFY_ACCESS_TOKEN // Get from Spotify OAuth 2.0 flow
})
// Get current user profile
const user = await spotify.me.get()
// Search for tracks
const trackResults = await spotify.search.tracks('bohemian rhapsody')
// Get user's playlists
const playlists = await spotify.me.playlists.get()
// Get user's saved tracks
const savedTracks = await spotify.me.tracks.get()
// Control playback
await spotify.player.play({ uris: ['spotify:track:4iV5W9uYEdYUVa79Axb7Rh'] })
await spotify.player.pause()
await spotify.player.next()
// Get currently playing track
const nowPlaying = await spotify.player.currentlyPlaying()
// Add tracks to a playlist
const playlist = spotify.playlist('playlist-id')
await playlist.tracks.add(['spotify:track:4iV5W9uYEdYUVa79Axb7Rh'])

GitHub API

import { GitHub } from '@remcostoeten/fync/github'
// Use environment variables for security
const github = GitHub({
 token: process.env.GITHUB_TOKEN // Get from GitHub settings > Developer settings > Personal access tokens
})
// Get user info
const user = await github.user('octocat').get()
// Get current authenticated user
const me = await github.me.get()
// Get repository details
const repo = await github.repo('facebook', 'react').get()
// Get repository issues
const issues = await github.repo('facebook', 'react').getIssues()
// Get a specific issue
const issue = await github.repo('facebook', 'react').getIssue(1)
// Get releases
const releases = await github.repo('facebook', 'react').getReleases()
const latestRelease = await github.repo('facebook', 'react').getLatestRelease()
// Search repositories
const searchResults = await github.search.repositories('react')
// Search users
const users = await github.search.users('octocat')
// Get rate limit info
const rateLimit = await github.rateLimit.get()
// Get notifications
const notifications = await github.notifications.get()

GitLab API

import { GitLab } from '@remcostoeten/fync/gitlab'
// Use environment variables for security
const gitlab = GitLab({
 token: process.env.GITLAB_TOKEN // Get from GitLab settings > Access tokens
})
// Get user info
const user = await gitlab.getUser('remcostoeten')
// Get current authenticated user
const me = await gitlab.getCurrentUser()
// Get project details
const project = await gitlab.getProject('gitlab-org/gitlab')
// Get project from URL
const projectFromUrl = await gitlab.getProjectFromUrl('https://gitlab.com/gitlab-org/gitlab')
// Get project issues
const issues = await gitlab.projects.getProjectIssues({ id: '278964' })
// Get a specific issue
const issue = await gitlab.projects.getProjectIssue({ 
 id: '278964', 
 issue_iid: '1' 
})
// Get merge requests
const mergeRequests = await gitlab.projects.getProjectMergeRequests({ id: '278964' })
// Get pipelines
const pipelines = await gitlab.projects.getProjectPipelines({ id: '278964' })
// Search projects
const searchResults = await gitlab.searchProjects('react', {
 order_by: 'stars',
 sort: 'desc'
})
// Get group details
const group = await gitlab.getGroup('gitlab-org')
// Get user statistics
const stats = await gitlab.getUserStats('remcostoeten')
console.log(`Total projects: ${stats.totalProjects}, Total stars: ${stats.totalStars}`)
// Get user's recent commits
const commits = await gitlab.getUserCommits('remcostoeten')
const latestCommit = await gitlab.getUserLatestCommit('remcostoeten')

NPM Registry API

import { NPM } from '@remcostoeten/fync/npm'
// No authentication required - public API
const npm = NPM({
 cache: true,
 cacheTTL: 300000 // 5 minutes
})
// Get package information
const packageInfo = await npm.package('react').get()
// Get latest version details
const latestVersion = await npm.package('react').latest()
// Get specific version
const specificVersion = await npm.package('react').version('18.0.0').get()
// Search packages
const searchResults = await npm.search.packages('typescript', {
 size: 10,
 quality: 0.8
})
// Get download statistics
const weeklyDownloads = await npm.downloads.package('react', 'last-week')
// Compare multiple packages
const frameworkStats = await npm.downloads.packages([
 'react', 'vue', 'angular', 'svelte'
], 'last-month')
// Get download trends over time
const downloadTrend = await npm.downloads.range('react', '2024-01-01', '2024-01-31')
// Direct chainable API access
const customQuery = await npm.api['@types']['node'].get()

Google Calendar API

import { createCalendarService } from '@remcostoeten/fync/google-calendar'
// Use environment variables for security
const calendar = createCalendarService({
 accessToken: process.env.GOOGLE_ACCESS_TOKEN // Get from Google OAuth 2.0 flow
})
// Get user's calendars
const calendars = await calendar.getCalendars()
// Get today's events
const todaysEvents = await calendar.getTodaysEvents('primary')
// Get upcoming events
const upcomingEvents = await calendar.getUpcomingEvents('primary', 10)
// Get events in date range
const startDate = new Date('2024-01-01')
const endDate = new Date('2024-01-31')
const eventsInRange = await calendar.getEventsInDateRange('primary', startDate, endDate)
// Search for events
const meetingEvents = await calendar.searchEvents('meeting', 'primary')
// Check if time slot is busy
const startTime = new Date('2024-01-15T10:00:00Z')
const endTime = new Date('2024-01-15T11:00:00Z')
const isBusy = await calendar.isTimeSlotBusy('primary', startTime, endTime)
// Get events from all calendars
const allEvents = await calendar.getAllCalendarEvents(100)
// Get calendar colors
const colors = await calendar.getColors()

📚 Complete Documentation

API Reference

Spotify

GitHub

GitLab

NPM Registry

Google Calendar

Configuration

Security

Setup Environment Variables

License

Contributing