@almosteffective/premiumize-api

A TypeScript library for interacting with the Premiumize.me API with full type safety and runtime validation.

Installation

npm install @almosteffective/premiumize-api
# or
pnpm add @almosteffective/premiumize-api

Quick Start

import { PremiumizeClient } from '@almosteffective/premiumize-api';

// Create a client instance (recommended method)
const client = PremiumizeClient.create('your-api-key-here');

// Or using the constructor directly
const client = new PremiumizeClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://custom-api-endpoint.com' // optional
});

// Get account info
const account = await client.accountInfo();
console.log(account);

// Create a transfer
const transfer = await client.createTransfer({
  src: 'magnet:?xt=urn:btih:...'
});
console.log(transfer);

// List transfers
const transfers = await client.listTransfers();
console.log(transfers);

// List folder contents
const folder = await client.listFolder();
console.log(folder);

API Methods

Account

• accountInfo(): Get account information and limits

Transfers

• createTransfer(options): Create a new transfer from magnet/torrent or NZB container
• listTransfers(): List all transfers
• deleteTransfers(options): Delete transfers
• clearTransfers(): Clear all finished transfers

Folders

• listFolder(options?): List contents of a folder
• createFolder(options): Create a new folder
• deleteFolder(options): Delete a folder
• renameFolder(options): Rename a folder
• searchFolder(options): Search files and folders

Items (Files)

• listAllItems(): List all files across all folders
• deleteItem(options): Delete a file
• renameItem(options): Rename a file
• getItemDetails(options): Get detailed information about a file

Zip

• generateZip(options): Generate a zip file from multiple items

Cache

• checkCache(options): Check if URLs are available in Premiumize cache

Services

• listServices(): Get list of supported services and domains

Detailed Usage Examples

Working with Folders

// List root folder
const rootFolder = await client.listFolder();

// List a specific folder with breadcrumbs
const folderWithBreadcrumbs = await client.listFolder({
  id: 'folder-id',
  includebreadcrumbs: true
});

// Create a new folder
const newFolder = await client.createFolder({
  name: 'My Downloads',
  parent_id: 'parent-folder-id'
});

// Rename a folder
await client.renameFolder({
  id: 'folder-id',
  name: 'New Folder Name'
});

// Delete a folder
await client.deleteFolder({
  id: 'folder-id'
});

// Search for items
const searchResults = await client.searchFolder({
  query: 'movie title'
});

Managing Transfers

// Create a new transfer
const transfer = await client.createTransfer({
  src: 'magnet:?xt=urn:btih:...',
  folder_id: 'destination-folder-uuid'
});

// List all transfers
const transfers = await client.listTransfers();

// Delete a specific transfer
await client.deleteTransfers({
  id: 'transfer-id'
});

// Clear all finished transfers
await client.clearTransfers();

Working with Files

// List all files across all folders
const allFiles = await client.listAllItems();

// Get detailed information about a file
const fileDetails = await client.getItemDetails({
  id: 'file-id'
});

// Rename a file
await client.renameItem({
  id: 'file-id',
  name: 'New File Name.ext'
});

// Delete a file
await client.deleteItem({
  id: 'file-id'
});

Utilities

// Check if URLs are in cache
const cacheCheck = await client.checkCache({
  items: ['https://example.com/file1.zip', 'https://example.com/file2.zip']
});

// Generate a zip file
const zipFile = await client.generateZip({
  files: ['file-id-1', 'file-id-2'],
  folders: ['folder-id-1']
});

// Get supported services
const services = await client.listServices();

Error Handling

The library provides comprehensive error handling with custom error types:

try {
  const result = await client.accountInfo();
  console.log(result);
} catch (error) {
  if (error instanceof PremiumizeError) {
    console.error('Premiumize API Error:', error.message);
    // Additional error details are available in error.internalError
  } else if (error instanceof HTTPError) {
    console.error('HTTP Request Error:', error.message);
  } else {
    console.error('Unexpected Error:', error.message);
  }
}

Configuration

Required Configuration

Only an API key is required to use the library. You can obtain your API key from your Premiumize account settings.

Optional Configuration

You can optionally provide a custom base URL if you're using a proxy or different endpoint:

const client = new PremiumizeClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://my-proxy.com/premiumize-api'
});

Testing

This library uses Vitest for testing with MSW (Mock Service Worker) to mock API requests. This allows us to test the library without making real API calls.

Running Tests

# Run tests in watch mode
pnpm test

# Run tests once
pnpm run test:run

# Run tests with coverage
pnpm run test:coverage

Test Structure

The tests are organized in the following way:

1. src/test/setup.ts - Sets up the MSW server and provides mock handlers for API endpoints
2. src/client.test.ts - Contains tests for the PremiumizeClient class and its methods

Each test case mocks the API responses to verify that the client correctly handles different scenarios, including:

• Successful API responses
• API errors
• Network errors
• Validation of request parameters

Adding New Tests

When adding new API methods to the library, make sure to add corresponding tests in src/client.test.ts. The pattern is:

1. Define a mock response in src/test/setup.ts (if it's a new endpoint)
2. Add a test case in src/client.test.ts that verifies the method works correctly
3. Test both success and error cases

Features

• Type Safety: Full TypeScript support with strict typing
• Schema Validation: Runtime validation using Zod schemas to ensure API responses match expected structure
• Error Handling: Comprehensive error handling with descriptive messages
• Easy Configuration: Simple setup with API key and optional custom base URL
• Comprehensive Testing: Full test coverage with mocked API responses

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Test
pnpm test

# Lint
pnpm run lint

License

MIT