feat(FileCollection): Get archive link by file ids with specific pages

BREAKING CHANGE: Change API of `getArchiveLinkByIds`

Added `pages` parameter to select only a few pages
per file to be added to the archive.

docs/api/cozy-stack-client.md

@@ -197,6 +197,9 @@ Deleted and design docs are filtered by default, thus documents are retrieved in
 <dt><a href="#OAuthClient">OAuthClient</a> : <code>object</code></dt>
 <dd><p>Document representing a io.cozy.oauth.clients</p>
 </dd>
+<dt><a href="#ArchivePages">ArchivePages</a> : <code>object</code></dt>
+<dd><p>Attributes used for get archive link by ids</p>
+</dd>
 <dt><a href="#FetchChangesReturnValue">FetchChangesReturnValue</a> ⇒ <code><a href="#FetchChangesReturnValue">FetchChangesReturnValue</a></code></dt>
 <dd><p>Use cozy-stack&#39;s _changes API for io.cozy.files
 Design docs are filtered by default, thus documents are retrieved in the
@@ -739,6 +742,7 @@ files associated to a specific document
     * [.download(file, versionId, filename)](#FileCollection+download)
     * [.fetchFileContentById(id)](#FileCollection+fetchFileContentById)
     * [.getBeautifulSize(file, decimal)](#FileCollection+getBeautifulSize)
+    * [.getArchiveLinkByIds(params)](#FileCollection+getArchiveLinkByIds) ⇒ <code>Promise.&lt;string&gt;</code>
     * [.isChildOf(child, parent)](#FileCollection+isChildOf) ⇒ <code>boolean</code>
     * [.statById(id, options)](#FileCollection+statById) ⇒ <code>object</code>
     * [.createDirectoryByPath(path)](#FileCollection+createDirectoryByPath) ⇒ <code>object</code>
@@ -1031,6 +1035,22 @@ Get a beautified size for a given file
 | file | <code>object</code> | io.cozy.files object |
 | decimal | <code>number</code> | number of decimal |
 
+<a name="FileCollection+getArchiveLinkByIds"></a>
+
+### fileCollection.getArchiveLinkByIds(params) ⇒ <code>Promise.&lt;string&gt;</code>
+Get the archive link for a list of files
+The generated archive is temporary and is not persisted
+
+**Kind**: instance method of [<code>FileCollection</code>](#FileCollection)  
+**Returns**: <code>Promise.&lt;string&gt;</code> - - The archive link  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| params | <code>object</code> | Parameters |
+| params.ids | <code>Array.&lt;string&gt;</code> | List of file ids |
+| [params.name] | <code>string</code> | Name of the archive (default: 'files') |
+| [params.pages] | [<code>Array.&lt;ArchivePages&gt;</code>](#ArchivePages) | Array of objects, with `id` the file identifier, and `page` the page number (1 is the first page) |
+
 <a name="FileCollection+isChildOf"></a>
 
 ### fileCollection.isChildOf(child, parent) ⇒ <code>boolean</code>
@@ -2753,6 +2773,19 @@ If this is the case, call the onRevocationChange callback
 
 **Kind**: instance method of [<code>OAuthClient</code>](#OAuthClient)  
 **Returns**: <code>Promise.&lt;boolean&gt;</code> - A Promise that resolves to `false` if client is still valid, or `true` if it has been revoked.  
+<a name="ArchivePages"></a>
+
+## ArchivePages : <code>object</code>
+Attributes used for get archive link by ids
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| id | <code>string</code> | Id of the file |
+| page | <code>number</code> | The page number |
+
 <a name="FetchChangesReturnValue"></a>
 
 ## FetchChangesReturnValue ⇒ [<code>FetchChangesReturnValue</code>](#FetchChangesReturnValue)

packages/cozy-stack-client/src/FileCollection.js

@@ -723,18 +723,40 @@ class FileCollection extends DocumentCollection {
 
   async downloadArchive(fileIds, notSecureFilename = 'files') {
     const filename = slugify(notSecureFilename)
-    const href = await this.getArchiveLinkByIds(fileIds, filename)
+    const href = await this.getArchiveLinkByIds({
+      ids: fileIds,
+      name: filename
+    })
     const fullpath = this.stackClient.fullpath(href)
     this.forceFileDownload(fullpath, filename + '.zip')
   }
 
-  async getArchiveLinkByIds(ids, name = 'files') {
+  /**
+   * Attributes used for get archive link by ids
+   *
+   * @typedef {object} ArchivePages
+   * @property {string} id - Id of the file
+   * @property {number} page - The page number
+   */
+
+  /**
+   * Get the archive link for a list of files
+   * The generated archive is temporary and is not persisted
+   *
+   * @param {object} params - Parameters
+   * @param {string[]} params.ids - List of file ids
+   * @param {string} [params.name] - Name of the archive (default: 'files')
+   * @param {ArchivePages[]} [params.pages] - Array of objects, with `id` the file identifier, and `page` the page number (1 is the first page)
+   * @returns {Promise<string>} - The archive link
+   */
+  async getArchiveLinkByIds({ ids, name = 'files', pages }) {
     const resp = await this.stackClient.fetchJSON('POST', '/files/archive', {
       data: {
         type: 'io.cozy.archives',
         attributes: {
           name,
-          ids
+          ids,
+          ...(pages && { pages })
         }
       }
     })

packages/cozy-stack-client/src/FileCollection.spec.js

@@ -1850,4 +1850,56 @@ describe('FileCollection', () => {
       )
     })
   })
+
+  describe('getArchiveLinkByIds', () => {
+    beforeEach(() => {
+      client.fetchJSON.mockResolvedValue({ links: { related: 'link' } })
+    })
+    afterEach(() => {
+      client.fetchJSON.mockReset()
+    })
+
+    it('should call the right route', async () => {
+      const ids = ['42', '43']
+      await collection.getArchiveLinkByIds({ ids })
+      expect(client.fetchJSON).toHaveBeenCalledWith('POST', '/files/archive', {
+        data: {
+          attributes: {
+            ids,
+            name: 'files'
+          },
+          type: 'io.cozy.archives'
+        }
+      })
+    })
+    it('should call the right route with a custom name', async () => {
+      const ids = ['42', '43']
+      const name = 'my-archive'
+      await collection.getArchiveLinkByIds({ ids, name })
+      expect(client.fetchJSON).toHaveBeenCalledWith('POST', '/files/archive', {
+        data: {
+          attributes: {
+            ids,
+            name
+          },
+          type: 'io.cozy.archives'
+        }
+      })
+    })
+    it('should call the right route with a specific page by file', async () => {
+      const ids = ['42', '43']
+      const pages = [{ id: '42', page: 1 }, { id: '43', page: 2 }]
+      await collection.getArchiveLinkByIds({ ids, pages })
+      expect(client.fetchJSON).toHaveBeenCalledWith('POST', '/files/archive', {
+        data: {
+          attributes: {
+            ids,
+            name: 'files',
+            pages
+          },
+          type: 'io.cozy.archives'
+        }
+      })
+    })
+  })
 })