@adbjs/sdk 1.0.0 → 2.0.0

package/dist/index.d.cts

@@ -162,17 +162,17 @@ declare class LinkResource 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'
      * )
      * ```
      */
-    infos(links: string | string[], password?: string): Promise<LinkInfoItem[] | undefined>;
+    infos(links: string | string[], password?: string): Promise<LinkInfosResponseData | undefined>;
     /**
      * Extract links from redirectors/link protectors
      *
@@ -180,10 +180,11 @@ declare class LinkResource 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)
      * ```
      */
-    redirector(link: string): Promise<string[] | undefined>;
+    redirector(link: string): Promise<RedirectorResponseData | undefined>;
     /**
      * Unlock a download link
      *
@@ -285,12 +286,6 @@ interface WatchOptions {
      * @default 'Ready'
      */
     stopOnStatus?: string;
-    /**
-     * Use live mode for reduced bandwidth (delta sync)
-     * When enabled, only changes are transmitted instead of full status
-     * @default false
-     */
-    useLiveMode?: boolean;
 }
 /**
  * Magnet/Torrent resource for managing torrent downloads
@@ -363,16 +358,38 @@ declare class MagnetResource extends BaseResource {
      */
     statusList(statusFilter?: 'active' | 'ready' | 'expired' | 'error'): Promise<MagnetStatusResponseData | undefined>;
     /**
-     * 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
      *
-     * 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.
+     * - ✅ Monitoring multiple active magnets simultaneously
+     * - ✅ Building real-time dashboards
+     * - ✅ High-frequency polling scenarios (every few seconds)
+     * - ❌ Watching a single specific magnet (use `watch()` instead)
      *
-     * @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
+     * ## Important notes
+     *
+     * - **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,27 +397,60 @@ declare class MagnetResource 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.
      */
-    statusLive(options: LiveStatusOptions, id?: number): Promise<MagnetStatusResponseData | undefined>;
+    statusLive(options: LiveStatusOptions): Promise<MagnetStatusResponseData | undefined>;
     /**
      * Delete a magnet
      *
@@ -434,9 +484,9 @@ declare class MagnetResource 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)
      * })
      * ```
      *
@@ -444,33 +494,32 @@ declare class MagnetResource extends BaseResource {
      * Files are now retrieved separately from magnet status (since v4.1)
      * Only available for magnets with status 'Ready'
      */
-    files(ids: number | number[]): Promise<MagnetFilesItem[] | undefined>;
+    files(ids: number | number[]): Promise<MagnetFilesResponseData | undefined>;
     /**
      * 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.
      */
     watch(id: number, options?: WatchOptions): Promise<MagnetStatusResponseData | undefined>;
 }
@@ -584,11 +633,11 @@ declare class UserResource 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)
      * ```
      */
-    getInfo(): Promise<UserInfo | undefined>;
+    getInfo(): Promise<UserResponseData | undefined>;
     /**
      * Get available hosts for the current user based on their subscription
      *

package/dist/index.d.ts

@@ -162,17 +162,17 @@ declare class LinkResource 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'
      * )
      * ```
      */
-    infos(links: string | string[], password?: string): Promise<LinkInfoItem[] | undefined>;
+    infos(links: string | string[], password?: string): Promise<LinkInfosResponseData | undefined>;
     /**
      * Extract links from redirectors/link protectors
      *
@@ -180,10 +180,11 @@ declare class LinkResource 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)
      * ```
      */
-    redirector(link: string): Promise<string[] | undefined>;
+    redirector(link: string): Promise<RedirectorResponseData | undefined>;
     /**
      * Unlock a download link
      *
@@ -285,12 +286,6 @@ interface WatchOptions {
      * @default 'Ready'
      */
     stopOnStatus?: string;
-    /**
-     * Use live mode for reduced bandwidth (delta sync)
-     * When enabled, only changes are transmitted instead of full status
-     * @default false
-     */
-    useLiveMode?: boolean;
 }
 /**
  * Magnet/Torrent resource for managing torrent downloads
@@ -363,16 +358,38 @@ declare class MagnetResource extends BaseResource {
      */
     statusList(statusFilter?: 'active' | 'ready' | 'expired' | 'error'): Promise<MagnetStatusResponseData | undefined>;
     /**
-     * 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
      *
-     * 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.
+     * - ✅ Monitoring multiple active magnets simultaneously
+     * - ✅ Building real-time dashboards
+     * - ✅ High-frequency polling scenarios (every few seconds)
+     * - ❌ Watching a single specific magnet (use `watch()` instead)
      *
-     * @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
+     * ## Important notes
+     *
+     * - **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,27 +397,60 @@ declare class MagnetResource 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.
      */
-    statusLive(options: LiveStatusOptions, id?: number): Promise<MagnetStatusResponseData | undefined>;
+    statusLive(options: LiveStatusOptions): Promise<MagnetStatusResponseData | undefined>;
     /**
      * Delete a magnet
      *
@@ -434,9 +484,9 @@ declare class MagnetResource 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)
      * })
      * ```
      *
@@ -444,33 +494,32 @@ declare class MagnetResource extends BaseResource {
      * Files are now retrieved separately from magnet status (since v4.1)
      * Only available for magnets with status 'Ready'
      */
-    files(ids: number | number[]): Promise<MagnetFilesItem[] | undefined>;
+    files(ids: number | number[]): Promise<MagnetFilesResponseData | undefined>;
     /**
      * 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.
      */
     watch(id: number, options?: WatchOptions): Promise<MagnetStatusResponseData | undefined>;
 }
@@ -584,11 +633,11 @@ declare class UserResource 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)
      * ```
      */
-    getInfo(): Promise<UserInfo | undefined>;
+    getInfo(): Promise<UserResponseData | undefined>;
     /**
      * Get available hosts for the current user based on their subscription
      *