refactor and improve docs

API.md

@@ -0,0 +1,203 @@
+# Documentation
+
+## CLI Tool
+
+### Installation
+```bash
+npm install -g soundcloud-sync
+```
+
+### Usage
+```
+Usage:
+  soundcloud-sync [options]
+
+Options:
+  --user, -u <value> (required)    SoundCloud username to fetch likes from
+  --limit, -l <value>              Number of latest likes to fetch
+  --folder, -f <value>             Output folder (default: ./music)
+  --help, -h                       Show this help message
+```
+
+### Debug Logging
+Add `LOG_LEVEL=debug` before any command to see detailed logs:
+```bash
+LOG_LEVEL=debug soundcloud-sync -u your-username
+```
+
+## Library
+
+### Installation
+
+#### Node.js
+```bash
+npm install soundcloud-sync
+# or
+yarn add soundcloud-sync
+```
+
+#### Deno
+```typescript
+import { soundCloudSync } from "https://raw.githubusercontent.com/realies/soundcloud-sync/master/mod.ts";
+```
+
+### Functions
+
+#### soundCloudSync(options)
+
+High-level function that combines all steps for ease of use.
+
+```typescript
+function soundCloudSync(options: SoundCloudSyncOptions): Promise<void>
+```
+
+#### getClient(profileName)
+
+Gets the SoundCloud client information needed for API requests.
+
+```typescript
+function getClient(profileName: string): Promise<Client>
+```
+
+#### getUserLikes(client, offset?, limit?)
+
+Fetches liked tracks for a SoundCloud user.
+
+```typescript
+function getUserLikes(
+  client: Client,
+  offset?: string,
+  limit?: number,
+): Promise<UserLike[]>
+```
+
+#### getMissingMusic(likes, folder?, callbacks?)
+
+Downloads missing tracks from a list of liked tracks.
+
+```typescript
+function getMissingMusic(
+  likes: UserLike[],
+  folder?: string,
+  callbacks?: Callbacks
+): Promise<DownloadResult[]>
+```
+
+### Types
+
+```typescript
+interface SoundCloudSyncOptions {
+  /** SoundCloud username to fetch likes from */
+  username: string;
+  /** Output folder for downloaded tracks (default: ./music) */
+  folder?: string;
+  /** Number of latest likes to fetch */
+  limit?: number;
+}
+
+interface Client {
+  /** Client ID for API authentication */
+  id: string;
+  /** API version string */
+  version: string;
+  /** User's URN (unique identifier) */
+  urn: string;
+}
+
+interface Track {
+  /** Track's unique identifier */
+  id: number;
+  /** Track title */
+  title: string;
+  /** Track artist */
+  artist: string;
+  /** URL to track artwork */
+  artwork_url?: string;
+  /** Media transcoding information */
+  media: {
+    /** Available audio formats */
+    transcodings: Array<{
+      /** URL to fetch audio data */
+      url: string;
+      /** Format details */
+      format: {
+        /** Streaming protocol (e.g., 'progressive') */
+        protocol: string;
+        /** Content type (e.g., 'audio/mpeg') */
+        mime_type: string;
+      };
+    }>;
+  };
+  /** Additional metadata from publisher */
+  publisher_metadata?: {
+    /** Artist name from publisher */
+    artist: string;
+    /** Release title from publisher */
+    release_title: string;
+  };
+}
+
+interface UserLike {
+  /** When the track was liked */
+  created_at: string;
+  /** The liked track's details */
+  track: Track;
+}
+
+interface Callbacks {
+  /** Called when starting to download a track */
+  onDownloadStart?: (track: Track) => void;
+  /** Called when a track has been downloaded */
+  onDownloadComplete?: (track: Track) => void;
+  /** Called when a track download fails */
+  onDownloadError?: (track: Track, error: unknown) => void;
+}
+
+interface DownloadResult {
+  /** Title of the downloaded track */
+  track: string;
+  /** FFmpeg process output */
+  ffmpeg: {
+    /** Standard output from FFmpeg */
+    stdout: string;
+    /** Standard error from FFmpeg */
+    stderr: string;
+  };
+}
+```
+
+### Examples
+
+```typescript
+// High-level usage
+import { soundCloudSync } from 'soundcloud-sync';
+
+await soundCloudSync({
+  username: 'your-username',
+  limit: 100,
+  folder: './my-music'
+});
+
+// Low-level usage with individual functions
+import { getClient, getUserLikes, getMissingMusic } from 'soundcloud-sync';
+
+const client = await getClient('your-username');
+const likes = await getUserLikes(client, '0', 100);
+const results = await getMissingMusic(likes, './my-music');
+
+// Process download results
+console.log('Downloaded tracks:', results.map(r => r.track));
+
+// Check for encoding issues
+const issues = results.filter(r => r.ffmpeg.stderr.includes('Warning'));
+if (issues.length > 0) {
+  console.warn('Some tracks had encoding warnings:', issues);
+}
+
+// Use callbacks for progress tracking
+const downloaded: Track[] = [];
+await getMissingMusic(likes, './my-music', {
+  onDownloadStart: (track) => console.log(`Starting ${track.title}`),
+  onDownloadComplete: (track) => downloaded.push(track),
+  onDownloadError: (track, error) => console.error(`Failed ${track.title}:`, error)
+});

README.md

@@ -2,8 +2,6 @@
 
 A library and CLI tool to sync your SoundCloud likes to local files.
 
-![](https://i.snipboard.io/ZfMQL5.jpg)
-
 ## Features
 
 - Download liked tracks from any SoundCloud profile
@@ -12,73 +10,40 @@ A library and CLI tool to sync your SoundCloud likes to local files.
 - Supports incremental syncing (only downloads new likes)
 - Can be used as a library in other projects
 
-## Usage
+## Quick Start
 
-The CLI accepts the following arguments:
-```bash
-<username>        # Required: SoundCloud username to fetch likes from
-[folder]          # Optional: Output folder (default: ./music)
---limit <number>  # Optional: Maximum number of likes to fetch
-```
-
-### Node.js
+### CLI Usage
 
 ```bash
 # Install globally
 npm install -g soundcloud-sync
 
-# Or install locally
-yarn add soundcloud-sync
-
-# Basic usage
-soundcloud-sync realies
-
-# Custom folder
-soundcloud-sync realies ./my-music
-
-# Limit number of likes
-soundcloud-sync realies --limit 100
-
-# With debug logs
-LOG_LEVEL=debug soundcloud-sync realies
+# Download your likes
+soundcloud-sync -u your-username
 ```
 
-### Deno
+### Library Usage
 
 ```bash
-# Install globally
-deno install -n soundcloud-sync --allow-net --allow-write --allow-read https://deno.land/x/soundcloud_sync/cli.ts
-
-# Basic usage
-soundcloud-sync realies
-
-# Custom folder
-soundcloud-sync realies ./my-music
-
-# Limit number of likes
-soundcloud-sync realies --limit 100
-
-# With debug logs
-LOG_LEVEL=debug soundcloud-sync realies
+# Install in your project
+npm install soundcloud-sync
+# or
+yarn add soundcloud-sync
 ```
 
-## Development
+```typescript
+import { soundCloudSync } from 'soundcloud-sync';
 
-Clone and install dependencies:
-```bash
-git clone https://github.com/realies/soundcloud-sync.git
-cd soundcloud-sync
-yarn install
+await soundCloudSync({
+  username: 'your-username',
+  limit: 100,
+  folder: './my-music'
+});
 ```
 
-Run locally:
-```bash
-# Basic usage
-yarn start realies
+## Documentation
 
-# With debug logs
-LOG_LEVEL=debug yarn start realies
-```
+- [API Reference](API.md)
 
 ## Releases
 

bin/soundcloud-sync.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
-require('ts-node/register');
-require('../src/cli.ts');
+import 'ts-node/register';
+import '../src/cli';