slskd-client

A complete TypeScript client for the slskd API.

🚀 Installation

npm install slskd-client

📖 Usage

Basic setup

import { SlskdClient } from 'slskd-client';

const client = new SlskdClient({
  baseUrl: 'http://localhost:5030',
  apiKey: 'your-api-key', // Optional if auth is disabled
  timeout: 30000, // Optional, 30s default
});

Authentication

// Check if security is enabled
const securityEnabled = await client.session.securityEnabled();

// Login if required
if (securityEnabled) {
  await client.session.login({
    username: 'your-username',
    password: 'your-password',
  });
}

// Verify authentication
const isAuth = await client.isAuthenticated();
console.log('Authenticated:', isAuth);

File search

// Start a search
const search = await client.searches.searchText({
  searchText: 'Daft Punk',
  filterResponses: true,
  minimumResponseFileCount: 1,
  searchTimeout: 15000,
});

console.log('Search ID:', search.id);
console.log('Response count:', search.responseCount);

// Get results
const responses = await client.searches.searchResponses(search.id);

responses.forEach((response) => {
  console.log(`\nUser: ${response.username}`);
  console.log(`Files: ${response.fileCount}`);

  response.files.forEach((file) => {
    console.log(`  - ${file.filename} (${file.size} bytes)`);
  });
});

// Stop a search
await client.searches.stop(search.id);

// Delete a search
await client.searches.delete(search.id);

Transfers

// Enqueue files to download
await client.transfers.enqueue({
  username: 'some-user',
  files: [{ filename: '@@Path\\To\\File.mp3', size: 5242880 }],
});

// Get all downloads
const downloads = await client.transfers.getAllDownloads();

downloads.forEach((transfer) => {
  console.log(`\nUser: ${transfer.username}`);

  transfer.directories.forEach((dir) => {
    console.log(`  Directory: ${dir.directory}`);

    dir.files.forEach((file) => {
      console.log(`    - ${file.filename}`);
      console.log(`      State: ${file.state}`);
      console.log(`      Progress: ${file.percentComplete}%`);
    });
  });
});

// Cancel a download
await client.transfers.cancelDownload('username', 'file-id', true);

// Remove completed downloads
await client.transfers.removeCompletedDownloads();

Users

// Get user info
const userInfo = await client.users.info('some-user');
console.log('Description:', userInfo.description);
console.log('Upload slots:', userInfo.uploadSlots);

// Get user status
const status = await client.users.status('some-user');
console.log('Presence:', status.presence);
console.log('Privileged:', status.isPrivileged);

// Browse user files
const browse = await client.users.browse('some-user');
console.log('Directory count:', browse.directoryCount);

browse.directories.forEach((dir) => {
  console.log(`\nDirectory: ${dir.name}`);
  console.log(`  Files: ${dir.fileCount}`);

  dir.files.forEach((file) => {
    console.log(`    - ${file.filename} (${file.size} bytes)`);
  });
});

Rooms

// List available rooms
const availableRooms = await client.rooms.getAll();
console.log('Available rooms:', availableRooms.length);

// Join a room
await client.rooms.join('electronic', false);

// Get joined rooms
const joinedRooms = await client.rooms.getAllJoined();

// Send a message to a room
await client.rooms.send('electronic', 'Hello everyone!');

// Get room messages
const messages = await client.rooms.getMessages('electronic');
messages.forEach((msg) => {
  console.log(`[${msg.timestamp}] ${msg.username}: ${msg.message}`);
});

// Leave a room
await client.rooms.leave('electronic');

Private conversations

// Get all conversations
const conversations = await client.conversations.getAll();

// Send a private message
await client.conversations.send('some-user', 'Hello!');

// Get messages for a conversation
const messages = await client.conversations.getMessages('some-user');

// Mark a conversation as read
await client.conversations.acknowledge('some-user');

// Delete a conversation
await client.conversations.delete('some-user');

Server and application state

// Get Soulseek server state
const serverState = await client.server.state();
console.log('Connected:', serverState.isConnected);
console.log('Address:', serverState.address);

// Connect to server
await client.server.connect();

// Disconnect from server
await client.server.disconnect();

// Get application state
const appState = await client.application.state();
console.log('Version:', appState.version.full);

// Check for updates
const version = await client.application.checkUpdates();
console.log('Update available:', version.isUpdateAvailable);

// Restart application
await client.application.restart();

Shares

// Get all shares
const shares = await client.shares.getAll();
console.log('Local shares:', shares.local.length);

shares.local.forEach((share) => {
  console.log(`\nShare: ${share.alias || share.id}`);
  console.log(`  Path: ${share.localPath}`);
  console.log(`  Directories: ${share.directories}`);
  console.log(`  Files: ${share.files}`);
});

// Start a shares scan
await client.shares.startScan();

// Cancel the scan
await client.shares.cancelScan();

// Get share contents
const contents = await client.shares.contents('share-id');

Files

// Get downloads directory
const downloadsDir = await client.files.getDownloadsDir();

// Get incomplete directory
const incompleteDir = await client.files.getIncompleteDir();

// Delete a downloaded file
await client.files.deleteDownloadedFile('/path/to/file.mp3');

// Delete a downloaded directory
await client.files.deleteDownloadedDirectory('/path/to/folder');

Logs and events

// Get logs
const logs = await client.logs.get({
  level: 'Information',
  startTimestamp: new Date(Date.now() - 3600000).toISOString(), // Last hour
});

logs.forEach((log) => {
  console.log(`[${log.level}] ${log.message}`);
});

// Get events
const events = await client.events.get({
  start: 0,
  end: 100,
});

🏗️ Project structure

slskd-client/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── SlskdClient.ts          # Main client class
│   ├── endpoints/              # API modules
│   │   ├── session.ts          # Authentication
│   │   ├── searches.ts         # Searches
│   │   ├── transfers.ts        # Downloads/Uploads
│   │   ├── users.ts            # Users
│   │   └── application.ts      # Application, server, etc.
│   ├── types/                  # TypeScript definitions
│   │   ├── Auth.ts
│   │   ├── Search.ts
│   │   ├── Transfers.ts
│   │   ├── Users.ts
│   │   └── Settings.ts
│   └── utils/
│       └── HttpClient.ts       # Generic HTTP client
├── package.json
├── tsconfig.json
└── README.md

🔧 Development

Install dependencies

npm install

Build

npm run build

Watch mode

npm run dev

📚 API Modules

The client exposes the following modules:

• session - Authentication and session management
• searches - File search
• transfers - Download and upload management
• users - User information and browsing
• application - Application state and control
• server - Soulseek server connection
• shares - Shares management
• rooms - Rooms (chat)
• conversations - Private messages
• options - Configuration
• files - Local file management
• logs - Application logs
• events - Event system

🔐 Security

If your slskd instance has authentication enabled:

1. Use an API key via the apiKey option
2. Or use client.session.login() with your credentials
3. Verify auth with client.isAuthenticated()

🤝 Contributing

Contributions are welcome! Please open an issue or pull request.

📄 License

MIT

🙏 Acknowledgements

This client is inspired by the slskd Python client and uses the slskd API.

📖 Resources

• slskd API documentation
• slskd Python client
• slskd on GitHub