New command: spo file version keep. Closes #6774

.devproxy/api-specs/sharepoint.yaml

@@ -104,6 +104,47 @@ paths:
       responses:
         200:
           description: OK
+  /_api/web/GetFileById({fileId})/versions/:
+    get:
+      parameters:
+        - name: fileId
+          in: path
+          required: true
+          schema:
+            type: string
+          example: "'19bbfec4-4425-4660-95cb-da1887baa7b9'"
+      security:
+        - delegated:
+            - AllSites.Read
+            - AllSites.Write
+            - AllSites.Manage
+            - AllSites.FullControl
+      responses:
+        200:
+          description: OK
+  /_api/web/GetFileById({fileId})/versions({versionId})/SetExpirationDate():
+    post:
+      parameters:
+        - name: fileId
+          in: path
+          required: true
+          schema:
+            type: string
+          example: "'19bbfec4-4425-4660-95cb-da1887baa7b9'"
+        - name: versionId
+          in: path
+          required: true
+          schema:
+            type: integer
+          example: 1030
+      security:
+        - delegated:
+            - AllSites.Write
+            - AllSites.Manage
+            - AllSites.FullControl
+      responses:
+        200:
+          description: OK
   /_api/web/GetFolderByServerRelativePath(DecodedUrl={folderPath}):
     get:
       parameters:

docs/docs/cmd/spo/file/file-version-keep.mdx

@@ -0,0 +1,68 @@
+import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# spo file version keep
+
+Ensure that a specific file version will never expire.
+
+## Usage
+
+```sh
+m365 spo file version keep [options]
+```
+
+## Options
+
+```md definition-list
+`-u, --webUrl <webUrl>`
+: The URL of the site where the file is located.
+
+`--fileUrl [fileUrl]`
+: The server- or site-relative decoded URL. Specify either `fileUrl` or `fileId` but not both.
+
+`-i, --fileId [fileId]`
+: The UniqueId (GUID) of the file. Specify either `fileUrl` or `fileId` but not both.
+
+`--label <label>`
+: Label of the version.
+```
+
+<Global />
+
+## Permissions
+
+<Tabs>
+  <TabItem value="Delegated" label="Delegated">
+
+  | Resource   | Permissions                                      |
+  |------------|--------------------------------------------------|
+  | SharePoint | AllSites.Write, AllSites.Manage, AllSites.FullControl |
+
+  </TabItem>
+  <TabItem value="Application" label="Application">
+
+  | Resource   | Permissions                                         |
+  |------------|-----------------------------------------------------|
+  | SharePoint | Sites.ReadWrite.All, Sites.Manage.All, Sites.FullControl.All |
+
+  </TabItem>
+</Tabs>
+
+## Examples
+
+Mark a file version as never expiring by file URL.
+
+```sh
+m365 spo file version keep --webUrl "https://contoso.sharepoint.com/sites/marketing" --fileUrl "/sites/marketing/Documents/report.docx" --label "6.0"
+```
+
+Mark a file version as never expiring by file ID.
+
+```sh
+m365 spo file version keep --webUrl "https://contoso.sharepoint.com/sites/marketing" --fileId "12345678-90ab-cdef-1234-567890abcdef" --label "6.0"
+```
+
+## Response
+
+The command won't return a response on success.

docs/src/config/sidebars.ts

@@ -2758,6 +2758,11 @@ const sidebars: SidebarsConfig = {
               label: 'file version get',
               id: 'cmd/spo/file/file-version-get'
             },
+            {
+              type: 'doc',
+              label: 'file version keep',
+              id: 'cmd/spo/file/file-version-keep'
+            },
             {
               type: 'doc',
               label: 'file version list',

src/m365/spo/commands.ts

@@ -84,6 +84,7 @@ export default {
   FILE_SHARINGLINK_SET: `${prefix} file sharinglink set`,
   FILE_VERSION_CLEAR: `${prefix} file version clear`,
   FILE_VERSION_GET: `${prefix} file version get`,
+  FILE_VERSION_KEEP: `${prefix} file version keep`,
   FILE_VERSION_LIST: `${prefix} file version list`,
   FILE_VERSION_REMOVE: `${prefix} file version remove`,
   FILE_VERSION_RESTORE: `${prefix} file version restore`,

src/m365/spo/commands/file/file-version-keep.spec.ts

@@ -0,0 +1,192 @@
+import assert from 'assert';
+import sinon from 'sinon';
+import auth from '../../../../Auth.js';
+import { cli } from '../../../../cli/cli.js';
+import { CommandInfo } from '../../../../cli/CommandInfo.js';
+import { Logger } from '../../../../cli/Logger.js';
+import { CommandError } from '../../../../Command.js';
+import request from '../../../../request.js';
+import { telemetry } from '../../../../telemetry.js';
+import { formatting } from '../../../../utils/formatting.js';
+import { pid } from '../../../../utils/pid.js';
+import { session } from '../../../../utils/session.js';
+import { sinonUtil } from '../../../../utils/sinonUtil.js';
+import { z } from 'zod';
+import commands from '../../commands.js';
+import command from './file-version-keep.js';
+
+describe(commands.FILE_VERSION_KEEP, () => {
+  let log: any[];
+  let logger: Logger;
+  let commandInfo: CommandInfo;
+  let commandOptionsSchema: z.ZodTypeAny;
+  const validWebUrl = "https://contoso.sharepoint.com";
+  const validFileUrl = "/Shared Documents/Document.docx";
+  const validFileId = "7a9b8bb6-d5c4-4de9-ab76-5210a7879e89";
+  const validLabel = "1.0";
+
+  before(() => {
+    sinon.stub(auth, 'restoreAuth').resolves();
+    sinon.stub(telemetry, 'trackEvent').resolves();
+    sinon.stub(pid, 'getProcessName').returns('');
+    sinon.stub(session, 'getId').returns('');
+    commandInfo = cli.getCommandInfo(command);
+    commandOptionsSchema = commandInfo.command.getSchemaToParse()!;
+    auth.connection.active = true;
+  });
+
+  beforeEach(() => {
+    log = [];
+    logger = {
+      log: async (msg: string) => {
+        log.push(msg);
+      },
+      logRaw: async (msg: string) => {
+        log.push(msg);
+      },
+      logToStderr: async (msg: string) => {
+        log.push(msg);
+      }
+    };
+  });
+
+  afterEach(() => {
+    sinonUtil.restore([
+      request.get,
+      request.post
+    ]);
+  });
+
+  after(() => {
+    sinon.restore();
+    auth.connection.active = false;
+  });
+
+  it('has correct name', () => {
+    assert.strictEqual(command.name, commands.FILE_VERSION_KEEP);
+  });
+
+  it('has a description', () => {
+    assert.notStrictEqual(command.description, null);
+  });
+
+  it('fails validation if webUrl is not a valid URL', async () => {
+    const actual = commandOptionsSchema.safeParse({ webUrl: 'foo', label: validLabel, fileUrl: validFileUrl });
+    assert.strictEqual(actual.success, false);
+  });
+
+  it('fails validation if fileId is not a valid GUID', async () => {
+    const actual = commandOptionsSchema.safeParse({ webUrl: validWebUrl, fileId: 'invalid' });
+    assert.strictEqual(actual.success, false);
+  });
+
+  it('fails validation if fileUrl and fileId are specified', async () => {
+    const actual = commandOptionsSchema.safeParse({ webUrl: validWebUrl, fileUrl: validFileUrl, fileId: validFileId });
+    assert.strictEqual(actual.success, false);
+  });
+
+  it('fails validation if label is not specified', async () => {
+    const actual = commandOptionsSchema.safeParse({ webUrl: validWebUrl, fileUrl: validFileUrl });
+    assert.strictEqual(actual.success, false);
+  });
+
+  it('passes validation if fileUrl is specified', async () => {
+    const actual = await command.validate({ options: { webUrl: validWebUrl, label: validLabel, fileUrl: validFileUrl } }, commandInfo);
+    assert.strictEqual(actual, true);
+  });
+
+  it('passes validation if fileId is specified', async () => {
+    const actual = await command.validate({ options: { webUrl: validWebUrl, label: validLabel, fileId: validFileId } }, commandInfo);
+    assert.strictEqual(actual, true);
+  });
+
+  it('ensures that a specific file version will never expire (fileUrl)', async () => {
+    sinon.stub(request, 'get').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileByServerRelativePath(DecodedUrl='${formatting.encodeQueryParameter(validFileUrl)}')/versions/?$filter=VersionLabel eq '${validLabel}'&$select=Id`) {
+        return {
+          value: [
+            {
+              ID: 1,
+              VersionLabel: validLabel
+            }
+          ]
+        };
+      }
+
+      throw 'Invalid request';
+    });
+
+    const postStub: sinon.SinonStub = sinon.stub(request, 'post').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileByServerRelativePath(DecodedUrl='${formatting.encodeQueryParameter(validFileUrl)}')/versions(1)/SetExpirationDate()`) {
+        return;
+      }
+
+      throw 'Invalid request';
+    });
+
+    await command.action(logger, { options: { webUrl: validWebUrl, fileUrl: validFileUrl, label: validLabel, verbose: true } });
+    assert.strictEqual(postStub.lastCall.args[0].url, `${validWebUrl}/_api/web/GetFileByServerRelativePath(DecodedUrl='${formatting.encodeQueryParameter(validFileUrl)}')/versions(1)/SetExpirationDate()`);
+  });
+
+  it('ensures that a specific file version will never expire (fileId)', async () => {
+    sinon.stub(request, 'get').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileById('${validFileId}')/versions/?$filter=VersionLabel eq '${validLabel}'&$select=Id`) {
+        return {
+          value: [
+            {
+              ID: 1,
+              VersionLabel: validLabel
+            }
+          ]
+        };
+      }
+
+      throw 'Invalid request';
+    });
+
+    const postStub: sinon.SinonStub = sinon.stub(request, 'post').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileById('${validFileId}')/versions(1)/SetExpirationDate()`) {
+        return;
+      }
+
+      throw 'Invalid request';
+    });
+
+    await command.action(logger, { options: { webUrl: validWebUrl, fileId: validFileId, label: validLabel, verbose: true } });
+    assert.strictEqual(postStub.lastCall.args[0].url, `${validWebUrl}/_api/web/GetFileById('${validFileId}')/versions(1)/SetExpirationDate()`);
+  });
+
+  it('correctly handles error when the specified version does not exist', async () => {
+    sinon.stub(request, 'get').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileByServerRelativePath(DecodedUrl='${formatting.encodeQueryParameter(validFileUrl)}')/versions/?$filter=VersionLabel eq '${validLabel}'&$select=Id`) {
+        return { value: [] };
+      }
+
+      throw 'Invalid request';
+    });
+    await assert.rejects(command.action(logger, { options: { webUrl: validWebUrl, fileUrl: validFileUrl, label: validLabel } }),
+      new CommandError(`Version with label '${validLabel}' not found.`));
+  });
+
+  it('correctly handles API OData error', async () => {
+    sinon.stub(request, 'get').callsFake(async (opts) => {
+      if (opts.url === `${validWebUrl}/_api/web/GetFileById('${validFileId}')/versions/?$filter=VersionLabel eq '${validLabel}'&$select=Id`) {
+        throw {
+          error: {
+            'odata.error': {
+              code: '-1, Microsoft.SharePoint.Client.InvalidOperationException',
+              message: {
+                value: 'Invalid version request'
+              }
+            }
+          }
+        };
+      }
+
+      throw 'Invalid request';
+    });
+
+    await assert.rejects(command.action(logger, { options: { webUrl: validWebUrl, fileId: validFileId, label: validLabel } }),
+      new CommandError('Invalid version request'));
+  });
+});