@adbjs/sdk 1.0.0 → 2.0.1

package/README.md

@@ -2,17 +2,18 @@
 
 Modern TypeScript SDK for the AllDebrid API v4.1.
 
-## Features
+## ✨ Features
 
-- ✨ **TypeScript-first** - Full type safety with auto-generated types from OpenAPI v4.1 spec
+- 🎯 **TypeScript-first** - Full type safety with auto-generated types from OpenAPI v4.1 spec
 - 🚀 **Modern** - Built with wretch, ESM + CJS support
 - 📦 **Tree-shakeable** - Import only what you need
 - 🔄 **Auto-retry** - Built-in retry logic with configurable options
-- 🎯 **Type-safe errors** - Typed error classes for better error handling
+- 🛡️ **Type-safe errors** - Typed error classes for better error handling
 - 📝 **Fully documented** - JSDoc comments with examples
 - ⚡ **API v4.1 optimized** - Designed and optimized for AllDebrid API v4.1
+- 💡 **Minimal footprint** - Only one runtime dependency (wretch)
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @adbjs/sdk
@@ -22,7 +23,7 @@ pnpm add @adbjs/sdk
 yarn add @adbjs/sdk
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ```typescript
 import { AllDebridClient } from '@adbjs/sdk'
@@ -45,14 +46,14 @@ const magnet = await client.magnet.upload('magnet:?xt=urn:btih:...')
 console.log('Magnet ID:', magnet.magnets[0].id)
 ```
 
-## API Reference
+## 📖 API Reference
 
 ### Client Configuration
 
 ```typescript
 const client = new AllDebridClient({
   apiKey: string          // Required: Your AllDebrid API key
-  agent?: string          // Optional: User agent (default: '@alldebrid/sdk')
+  agent?: string          // Optional: User agent (default: '@adbjs/sdk')
   baseUrl?: string        // Optional: API base URL
   timeout?: number        // Optional: Request timeout in ms (default: 30000)
   retry?: boolean         // Optional: Enable auto-retry (default: true)
@@ -171,10 +172,8 @@ counter = firstCall.counter // Important: Use the returned counter value
 const secondCall = await client.magnet.statusLive({ session, counter })
 console.log('Delta sync (only changes):', secondCall.magnets)
 
-// Live mode can also track a specific magnet
+// Update counter for subsequent calls
 counter = secondCall.counter
-const specificMagnet = await client.magnet.statusLive({ session, counter }, 123)
-console.log('Changes for magnet 123:', specificMagnet.magnets)
 
 // ===== Magnet management =====
 
@@ -192,27 +191,16 @@ files?.forEach((file) => {
 
 // ===== Watch: Monitor magnet progress with automatic polling =====
 
-// Standard mode: Full status check on each poll
+// Watch a magnet until it's ready
 await client.magnet.watch(123, {
   interval: 3000, // Check every 3 seconds
-  maxAttempts: 30, // Stop after 30 attempts
+  maxAttempts: 30, // Stop after 30 attempts (0 = infinite)
   stopOnStatus: 'Ready', // Stop when magnet is ready
   onUpdate: (status) => {
     const magnet = status.magnets[0]
     console.log(`Progress: ${magnet?.status} - ${magnet?.downloaded || 0}%`)
   },
 })
-
-// Live mode: Delta sync for reduced bandwidth (recommended for long-running monitors)
-await client.magnet.watch(123, {
-  useLiveMode: true, // Enable live mode
-  interval: 2000, // Check every 2 seconds
-  maxAttempts: 0, // 0 = infinite polling
-  onUpdate: (status) => {
-    // Only called when the magnet status changes
-    console.log('Magnet updated:', status.magnets[0])
-  },
-})
 ```
 
 ### Host Resource
@@ -272,7 +260,7 @@ const newVouchers = await client.voucher.generateVouchers(10, 30)
 console.log('Generated vouchers:', newVouchers?.codes)
 ```
 
-## Error Handling
+## 🛡️ Error Handling
 
 The SDK provides typed error classes for better error handling:
 
@@ -298,7 +286,7 @@ try {
 }
 ```
 
-## Type Safety
+## 🎯 Type Safety
 
 All responses are fully typed using types generated from the official AllDebrid API v4.1 OpenAPI specification:
 
@@ -306,7 +294,7 @@ All responses are fully typed using types generated from the official AllDebrid
 import type { GetLinkUnlockResponse, GetMagnetStatusResponse, GetUserResponse } from '@adbjs/sdk'
 ```
 
-## Development
+## 🏗️ Development
 
 ```bash
 # Install dependencies
@@ -325,11 +313,11 @@ pnpm test
 pnpm typecheck
 ```
 
-## License
+## 📝 License
 
 MIT
 
-## Links
+## 🔗 Links
 
 - [AllDebrid API Documentation](https://docs.alldebrid.com/)
 - [GitHub Repository](https://github.com/Trisard/alldebrid-ts)

package/dist/index.cjs

@@ -159,11 +159,11 @@ var LinkResource = class extends BaseResource {
    *
    * @example
    * ```ts
-   * const info = await client.link.infos('https://example.com/file.zip')
-   * console.log(info)
+   * const data = await client.link.infos('https://example.com/file.zip')
+   * console.log(data.infos)
    *
    * // With password
-   * const protectedInfo = await client.link.infos(
+   * const protectedData = await client.link.infos(
    *   'https://example.com/protected.zip',
    *   'mypassword'
    * )
@@ -172,12 +172,7 @@ var LinkResource = class extends BaseResource {
   async infos(links, password) {
     const linksArray = Array.isArray(links) ? links : [links];
     const params = password ? { password } : void 0;
-    const data = await this.post(
-      "/link/infos",
-      { "link[]": linksArray },
-      params
-    );
-    return data?.infos;
+    return this.post("/link/infos", { "link[]": linksArray }, params);
   }
   /**
    * Extract links from redirectors/link protectors
@@ -186,14 +181,14 @@ var LinkResource = class extends BaseResource {
    *
    * @example
    * ```ts
-   * const links = await client.link.redirector('https://linkprotector.com/abc123')
+   * const data = await client.link.redirector('https://linkprotector.com/abc123')
+   * console.log(data.links)
    * ```
    */
   async redirector(link) {
-    const data = await this.post("/link/redirector", {
+    return this.post("/link/redirector", {
       link
     });
-    return data?.links;
   }
   /**
    * Unlock a download link
@@ -363,16 +358,38 @@ var MagnetResource = class extends BaseResource {
     return this.post("/magnet/status", body);
   }
   /**
-   * Get magnet status using live mode for reduced bandwidth consumption
+   * Get magnet status using live mode for bandwidth-optimized delta synchronization
+   *
+   * Live mode is designed for monitoring multiple magnets efficiently by only transmitting
+   * changes between polling intervals, drastically reducing bandwidth usage for dashboards
+   * and real-time monitoring applications.
+   *
+   * ## How it works
+   *
+   * 1. **Session initialization**: Generate a random session ID and start with counter = 0
+   * 2. **First call (fullsync)**: Returns ALL magnets with `fullsync: true`
+   * 3. **Update counter**: Use the `counter` value returned by the API for the next call
+   * 4. **Subsequent calls (delta)**: Returns ONLY magnets that changed since last call
+   * 5. **Repeat**: Keep calling with updated counter to receive only deltas
+   *
+   * ## When to use
+   *
+   * - ✅ Monitoring multiple active magnets simultaneously
+   * - ✅ Building real-time dashboards
+   * - ✅ High-frequency polling scenarios (every few seconds)
+   * - ❌ Watching a single specific magnet (use `watch()` instead)
    *
-   * Live mode uses delta synchronization - only changes since the last call are transmitted.
-   * On the first call (counter=0), all data is returned with `fullsync: true`.
-   * Subsequent calls return only modifications.
+   * ## Important notes
    *
-   * @param options - Live mode options
-   * @param options.session - Session ID (generate once per session and reuse)
-   * @param options.counter - Synchronization counter (start at 0, use returned counter for next call)
-   * @param id - Optional magnet ID to filter a specific magnet
+   * - **Don't use the `id` parameter**: Passing an ID defeats the purpose of live mode
+   *   as it disables delta sync and behaves like a regular `status()` call
+   * - **Session persistence**: Keep the same session ID for the entire monitoring session
+   * - **Counter tracking**: Always update the counter with the value returned by the API
+   * - **Empty deltas**: When no magnets changed, `magnets` will be an empty array
+   *
+   * @param options - Live mode session options
+   * @param options.session - Unique session ID (generate once: `Math.floor(Math.random() * 1000000)`)
+   * @param options.counter - Sync counter (start at 0, then use value from previous API response)
    *
    * @example
    * ```ts
@@ -380,34 +397,64 @@ var MagnetResource = class extends BaseResource {
    * const session = Math.floor(Math.random() * 1000000)
    * let counter = 0
    *
-   * // First call - full sync
+   * // First call - returns all magnets (fullsync: true)
    * const firstCall = await client.magnet.statusLive({ session, counter })
    * console.log('Full sync:', firstCall.fullsync) // true
-   * console.log('All magnets:', firstCall.magnets)
-   *
-   * // Update counter with value returned by API
-   * counter = firstCall.counter
+   * console.log('All magnets:', firstCall.magnets) // Array of all magnets
+   * counter = firstCall.counter // Update counter for next call
    *
-   * // Second call - only changes
+   * // Second call - returns only magnets that changed
+   * await new Promise(resolve => setTimeout(resolve, 3000)) // Wait 3 seconds
    * const secondCall = await client.magnet.statusLive({ session, counter })
-   * console.log('Delta sync:', secondCall.magnets) // Only modified magnets
+   * console.log('Delta sync:', secondCall.magnets) // Only changed magnets
+   * counter = secondCall.counter
+   *
+   * // Example: Monitor all magnets until none are active
+   * const activeMagnets = new Map()
+   *
+   * while (true) {
+   *   const response = await client.magnet.statusLive({ session, counter })
+   *   counter = response.counter ?? counter
+   *
+   *   // Update our local state with changes
+   *   if (response.fullsync) {
+   *     activeMagnets.clear()
+   *     response.magnets?.forEach(m => activeMagnets.set(m.id, m))
+   *   } else {
+   *     response.magnets?.forEach(m => {
+   *       if (m.status === 'Ready' || m.status === 'Error' || m.status === 'Expired') {
+   *         activeMagnets.delete(m.id)
+   *       } else {
+   *         activeMagnets.set(m.id, m)
+   *       }
+   *     })
+   *   }
+   *
+   *   // Display current state
+   *   console.log(`Active downloads: ${activeMagnets.size}`)
+   *   activeMagnets.forEach(m => {
+   *     console.log(`  ${m.filename}: ${m.status} - ${m.downloaded}/${m.size} bytes`)
+   *   })
+   *
+   *   // Stop when no more active magnets
+   *   if (activeMagnets.size === 0) {
+   *     console.log('All downloads completed!')
+   *     break
+   *   }
    *
-   * // Filter specific magnet in live mode
-   * const magnetLive = await client.magnet.statusLive({ session, counter }, 123)
+   *   await new Promise(resolve => setTimeout(resolve, 3000))
+   * }
    * ```
    *
    * @remarks
-   * This is ideal for real-time dashboards or frequent polling scenarios
-   * as it significantly reduces bandwidth usage by transmitting only changes.
+   * This method is ideal for scenarios where you're monitoring multiple magnets and want
+   * to minimize bandwidth. For simple single-magnet monitoring, use `watch()` instead.
    */
-  async statusLive(options, id) {
+  async statusLive(options) {
     const body = {
       session: options.session,
       counter: options.counter
     };
-    if (id !== void 0) {
-      body.id = id;
-    }
     return this.post("/magnet/status", body);
   }
   /**
@@ -452,9 +499,9 @@ var MagnetResource = class extends BaseResource {
    *
    * @example
    * ```ts
-   * const files = await client.magnet.files(123)
-   * files?.forEach(file => {
-   *   console.log(file.filename, file.link)
+   * const data = await client.magnet.files(123)
+   * data?.magnets?.forEach(magnet => {
+   *   console.log(magnet.filename, magnet.files)
    * })
    * ```
    *
@@ -468,56 +515,40 @@ var MagnetResource = class extends BaseResource {
     for (const id of idsArray) {
       formData.append("id[]", String(id));
     }
-    const data = await this.postFormData("/magnet/files", formData);
-    return data?.magnets;
+    return this.postFormData("/magnet/files", formData);
   }
   /**
    * Watch a magnet's status with automatic polling
    *
+   * This is a simple helper that polls the status of a specific magnet until it reaches
+   * a target status (default: 'Ready'). For advanced use cases with multiple magnets
+   * or bandwidth optimization, use `statusLive()` directly instead.
+   *
    * @param id - The magnet ID to watch
    * @param options - Watch options
    * @param options.interval - Polling interval in milliseconds (default: 3000)
    * @param options.maxAttempts - Maximum polling attempts, 0 for infinite (default: 0)
    * @param options.onUpdate - Callback called on each status update
    * @param options.stopOnStatus - Stop when magnet reaches this status (default: 'Ready')
-   * @param options.useLiveMode - Use live mode for reduced bandwidth (default: false)
    *
    * @example
    * ```ts
-   * // Standard mode
    * await client.magnet.watch(123, {
    *   onUpdate: (status) => console.log('Status:', status.magnets[0]?.status),
    *   stopOnStatus: 'Ready'
    * })
-   *
-   * // Live mode for reduced bandwidth
-   * await client.magnet.watch(123, {
-   *   useLiveMode: true,
-   *   interval: 2000,
-   *   onUpdate: (status) => console.log('Update:', status)
-   * })
    * ```
+   *
+   * @remarks
+   * For monitoring multiple magnets efficiently, use `statusLive()` directly.
+   * See the `statusLive()` documentation for details on delta synchronization.
    */
   async watch(id, options = {}) {
-    const {
-      interval = 3e3,
-      maxAttempts = 0,
-      onUpdate,
-      stopOnStatus = "Ready",
-      useLiveMode = false
-    } = options;
+    const { interval = 3e3, maxAttempts = 0, onUpdate, stopOnStatus = "Ready" } = options;
     let attempt = 0;
-    let session;
-    let counter = 0;
-    if (useLiveMode) {
-      session = Math.floor(Math.random() * 1e6);
-    }
     while (maxAttempts === 0 || attempt < maxAttempts) {
       attempt++;
-      const status = useLiveMode && session !== void 0 ? await this.statusLive({ session, counter }, id) : await this.status(id);
-      if (useLiveMode && status?.counter !== void 0) {
-        counter = status.counter;
-      }
+      const status = await this.status(id);
       onUpdate?.(status);
       const magnet = status?.magnets?.[0];
       if (magnet?.status === stopOnStatus) {
@@ -643,13 +674,12 @@ var UserResource = class extends BaseResource {
    *
    * @example
    * ```ts
-   * const user = await client.user.getInfo()
-   * console.log(user.username, user.isPremium)
+   * const data = await client.user.getInfo()
+   * console.log(data.user.username, data.user.isPremium)
    * ```
    */
   async getInfo() {
-    const data = await this.get("/user");
-    return data?.user;
+    return this.get("/user");
   }
   /**
    * Get available hosts for the current user based on their subscription
@@ -882,7 +912,7 @@ var VoucherResource = class extends BaseResource {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.alldebrid.com/v4.1";
-var DEFAULT_AGENT = "@alldebrid/sdk";
+var DEFAULT_AGENT = "@adbjs/sdk";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var AllDebridClient = class {