diff --git a/docs/hubs.md b/docs/hubs.md index e958b69d..08ebb75e 100644 --- a/docs/hubs.md +++ b/docs/hubs.md @@ -7,6 +7,10 @@ List Box Hubs for the current user * [`box hubs:copy ID`](#box-hubscopy-id) * [`box hubs:create TITLE`](#box-hubscreate-title) * [`box hubs:delete ID`](#box-hubsdelete-id) +* [`box hubs:document:blocks ID PAGEID`](#box-hubsdocumentblocks-id-pageid) +* [`box hubs:document:blocks:list ID PAGEID`](#box-hubsdocumentblockslist-id-pageid) +* [`box hubs:document:pages ID`](#box-hubsdocumentpages-id) +* [`box hubs:document:pages:list ID`](#box-hubsdocumentpageslist-id) * [`box hubs:enterprise`](#box-hubsenterprise) * [`box hubs:get ID`](#box-hubsget-id) * [`box hubs:items ID`](#box-hubsitems-id) @@ -178,6 +182,186 @@ EXAMPLES _See code: [src/commands/hubs/delete.js](https://github.com/box/boxcli/blob/v4.7.0/src/commands/hubs/delete.js)_ +## `box hubs:document:blocks ID PAGEID` + +Retrieve sorted Hub Document Blocks for a specific hub document page, excluding items. Results are organized by parent_id and include only blocks on that page, not sub pages or their content blocks. + +``` +USAGE + $ box hubs:document:blocks ID PAGEID [-t ] [--as-user ] [--no-color] [--json | --csv] [-s | + --save-to-file-path ] [--fields ] [--bulk-file-path ] [-h] [-v] [-y] [-q] [--max-items ] + +ARGUMENTS + ID ID of the Box Hub + PAGEID ID of the page in the Box Hub document + +FLAGS + -h, --help Show CLI help + -q, --quiet Suppress any non-error output to stderr + -s, --save Save report to default reports folder on disk + -t, --token= Provide a token to perform this call + -v, --verbose Show verbose output, which can be helpful for debugging + -y, --yes Automatically respond yes to all confirmation prompts + --as-user= Provide an ID for a user + --bulk-file-path= File path to bulk .csv or .json objects + --csv Output formatted CSV + --fields= Comma separated list of fields to show + --json Output formatted JSON + --max-items= A value that indicates the maximum number of results to return. This only specifies a + maximum boundary and will not guarantee the minimum number of results returned. When + the max-items (x) is greater than 1000, then the maximum ceil(x/1000) requests will + be made. + --no-color Turn off colors for logging + --save-to-file-path= Override default file path to save report + +DESCRIPTION + Retrieve sorted Hub Document Blocks for a specific hub document page, excluding items. Results are organized by + parent_id and include only blocks on that page, not sub pages or their content blocks. + +ALIASES + $ box hubs:document:blocks:list + +EXAMPLES + $ box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865 + + $ box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865 --max-items 50 +``` + +_See code: [src/commands/hubs/document/blocks.js](https://github.com/box/boxcli/blob/v4.7.0/src/commands/hubs/document/blocks.js)_ + +## `box hubs:document:blocks:list ID PAGEID` + +Retrieve sorted Hub Document Blocks for a specific hub document page, excluding items. Results are organized by parent_id and include only blocks on that page, not sub pages or their content blocks. + +``` +USAGE + $ box hubs:document:blocks:list ID PAGEID [-t ] [--as-user ] [--no-color] [--json | --csv] [-s | + --save-to-file-path ] [--fields ] [--bulk-file-path ] [-h] [-v] [-y] [-q] [--max-items ] + +ARGUMENTS + ID ID of the Box Hub + PAGEID ID of the page in the Box Hub document + +FLAGS + -h, --help Show CLI help + -q, --quiet Suppress any non-error output to stderr + -s, --save Save report to default reports folder on disk + -t, --token= Provide a token to perform this call + -v, --verbose Show verbose output, which can be helpful for debugging + -y, --yes Automatically respond yes to all confirmation prompts + --as-user= Provide an ID for a user + --bulk-file-path= File path to bulk .csv or .json objects + --csv Output formatted CSV + --fields= Comma separated list of fields to show + --json Output formatted JSON + --max-items= A value that indicates the maximum number of results to return. This only specifies a + maximum boundary and will not guarantee the minimum number of results returned. When + the max-items (x) is greater than 1000, then the maximum ceil(x/1000) requests will + be made. + --no-color Turn off colors for logging + --save-to-file-path= Override default file path to save report + +DESCRIPTION + Retrieve sorted Hub Document Blocks for a specific hub document page, excluding items. Results are organized by + parent_id and include only blocks on that page, not sub pages or their content blocks. + +ALIASES + $ box hubs:document:blocks:list + +EXAMPLES + $ box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865 + + $ box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865 --max-items 50 +``` + +## `box hubs:document:pages ID` + +Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages + +``` +USAGE + $ box hubs:document:pages ID [-t ] [--as-user ] [--no-color] [--json | --csv] [-s | --save-to-file-path + ] [--fields ] [--bulk-file-path ] [-h] [-v] [-y] [-q] [--max-items ] + +ARGUMENTS + ID ID of the Box Hub + +FLAGS + -h, --help Show CLI help + -q, --quiet Suppress any non-error output to stderr + -s, --save Save report to default reports folder on disk + -t, --token= Provide a token to perform this call + -v, --verbose Show verbose output, which can be helpful for debugging + -y, --yes Automatically respond yes to all confirmation prompts + --as-user= Provide an ID for a user + --bulk-file-path= File path to bulk .csv or .json objects + --csv Output formatted CSV + --fields= Comma separated list of fields to show + --json Output formatted JSON + --max-items= A value that indicates the maximum number of results to return. This only specifies a + maximum boundary and will not guarantee the minimum number of results returned. When + the max-items (x) is greater than 1000, then the maximum ceil(x/1000) requests will + be made. + --no-color Turn off colors for logging + --save-to-file-path= Override default file path to save report + +DESCRIPTION + Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages + +ALIASES + $ box hubs:document:pages:list + +EXAMPLES + $ box hubs:document:pages 12345 + + $ box hubs:document:pages 12345 --max-items 50 +``` + +_See code: [src/commands/hubs/document/pages.js](https://github.com/box/boxcli/blob/v4.7.0/src/commands/hubs/document/pages.js)_ + +## `box hubs:document:pages:list ID` + +Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages + +``` +USAGE + $ box hubs:document:pages:list ID [-t ] [--as-user ] [--no-color] [--json | --csv] [-s | --save-to-file-path + ] [--fields ] [--bulk-file-path ] [-h] [-v] [-y] [-q] [--max-items ] + +ARGUMENTS + ID ID of the Box Hub + +FLAGS + -h, --help Show CLI help + -q, --quiet Suppress any non-error output to stderr + -s, --save Save report to default reports folder on disk + -t, --token= Provide a token to perform this call + -v, --verbose Show verbose output, which can be helpful for debugging + -y, --yes Automatically respond yes to all confirmation prompts + --as-user= Provide an ID for a user + --bulk-file-path= File path to bulk .csv or .json objects + --csv Output formatted CSV + --fields= Comma separated list of fields to show + --json Output formatted JSON + --max-items= A value that indicates the maximum number of results to return. This only specifies a + maximum boundary and will not guarantee the minimum number of results returned. When + the max-items (x) is greater than 1000, then the maximum ceil(x/1000) requests will + be made. + --no-color Turn off colors for logging + --save-to-file-path= Override default file path to save report + +DESCRIPTION + Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages + +ALIASES + $ box hubs:document:pages:list + +EXAMPLES + $ box hubs:document:pages 12345 + + $ box hubs:document:pages 12345 --max-items 50 +``` + ## `box hubs:enterprise` List Box Hubs across the enterprise. This call requires an admin or hub co-admin of an enterprise with GCM scope. Otherwise, Box returns a 403 status code with the message `The request requires higher privileges than provided by the access token.` See https://developer.box.com/guides/api-calls/permissions-and-errors/scopes#global-content-manager-gcm diff --git a/src/commands/hubs/document/blocks.js b/src/commands/hubs/document/blocks.js new file mode 100644 index 00000000..c4ba5eb4 --- /dev/null +++ b/src/commands/hubs/document/blocks.js @@ -0,0 +1,55 @@ +'use strict'; + +const { Args } = require('@oclif/core'); +const BoxCommand = require('../../../box-command'); +const PaginationUtilities = require('../../../pagination-utils'); + +class HubsListDocumentBlocksCommand extends BoxCommand { + async run() { + const { args } = await this.parse(HubsListDocumentBlocksCommand); + const queryParams = { + hubId: args.id, + pageId: args.pageId, + }; + + const blocks = await this.markerPagination( + (pageQueryParams) => + this.tsClient.hubDocument.getHubDocumentBlocksV2025R0( + pageQueryParams + ), + queryParams + ); + await this.output(blocks); + } +} + +HubsListDocumentBlocksCommand.aliases = ['hubs:document:blocks:list']; +HubsListDocumentBlocksCommand.description = + 'Retrieve sorted Hub Document Blocks for a specific hub document page, excluding items. Results are organized by parent_id and include only blocks on that page, not sub pages or their content blocks.'; +HubsListDocumentBlocksCommand.examples = [ + 'box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865', + 'box hubs:document:blocks 12345 55c8361a-012a-4fa1-a724-b7ef1cd87865 --max-items 50', +]; +HubsListDocumentBlocksCommand._endpoint = 'get_hub_document_blocks'; + +HubsListDocumentBlocksCommand.flags = { + ...BoxCommand.flags, + ...PaginationUtilities.flags, +}; + +HubsListDocumentBlocksCommand.args = { + id: Args.string({ + name: 'id', + required: true, + hidden: false, + description: 'ID of the Box Hub', + }), + pageId: Args.string({ + name: 'page-id', + required: true, + hidden: false, + description: 'ID of the page in the Box Hub document', + }), +}; + +module.exports = HubsListDocumentBlocksCommand; diff --git a/src/commands/hubs/document/pages.js b/src/commands/hubs/document/pages.js new file mode 100644 index 00000000..6e3d0c45 --- /dev/null +++ b/src/commands/hubs/document/pages.js @@ -0,0 +1,47 @@ +'use strict'; + +const { Args } = require('@oclif/core'); +const BoxCommand = require('../../../box-command'); +const PaginationUtilities = require('../../../pagination-utils'); + +class HubsListDocumentPagesCommand extends BoxCommand { + async run() { + const { args } = await this.parse(HubsListDocumentPagesCommand); + const queryParams = { + hubId: args.id, + }; + + const pages = await this.markerPagination( + (pageQueryParams) => + this.tsClient.hubDocument.getHubDocumentPagesV2025R0( + pageQueryParams + ), + queryParams + ); + await this.output(pages); + } +} + +HubsListDocumentPagesCommand.aliases = ['hubs:document:pages:list']; +HubsListDocumentPagesCommand.description = 'Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages'; +HubsListDocumentPagesCommand.examples = [ + 'box hubs:document:pages 12345', + 'box hubs:document:pages 12345 --max-items 50', +]; +HubsListDocumentPagesCommand._endpoint = 'get_hub_document_pages'; + +HubsListDocumentPagesCommand.flags = { + ...BoxCommand.flags, + ...PaginationUtilities.flags, +}; + +HubsListDocumentPagesCommand.args = { + id: Args.string({ + name: 'id', + required: true, + hidden: false, + description: 'ID of the Box Hub', + }), +}; + +module.exports = HubsListDocumentPagesCommand; diff --git a/test/commands/hubs.test.js b/test/commands/hubs.test.js index b484feb9..1bd3209a 100644 --- a/test/commands/hubs.test.js +++ b/test/commands/hubs.test.js @@ -243,6 +243,84 @@ describe('Hubs', function () { }); }); + describe('hubs:document:pages', function () { + const response = JSON.parse(getFixture('hubs/get_hub_document_pages')); + + test + .nock(TEST_API_ROOT, (api) => + api + .get('/2.0/hub_document_pages') + .query({ + hub_id: '12345', + limit: 2, + }) + .reply(200, response) + ) + .stdout() + .command([ + 'hubs:document:pages', + '12345', + '--max-items=2', + '--json', + '--token=test', + ]) + .it('lists hub document pages', (context) => { + assert.deepEqual(JSON.parse(context.stdout), [ + { + id: 'page_1', + type: 'page', + titleFragment: 'Overview', + }, + { + id: 'page_2', + type: 'page', + parentId: 'page_1', + titleFragment: 'Launch Plan', + }, + ]); + }); + }); + + describe('hubs:document:blocks', function () { + const response = JSON.parse(getFixture('hubs/get_hub_document_blocks')); + + test + .nock(TEST_API_ROOT, (api) => + api + .get('/2.0/hub_document_blocks') + .query({ + hub_id: '12345', + page_id: 'page_1', + limit: 2, + }) + .reply(200, response) + ) + .stdout() + .command([ + 'hubs:document:blocks', + '12345', + 'page_1', + '--max-items=2', + '--json', + '--token=test', + ]) + .it('lists hub document blocks for a page', (context) => { + assert.deepEqual(JSON.parse(context.stdout), [ + { + id: 'block_1', + type: 'section_title', + parentId: 'page_1', + fragment: 'Goals', + }, + { + id: 'block_2', + type: 'item_list', + parentId: 'page_1', + }, + ]); + }); + }); + describe('hubs:get', function () { const response = JSON.parse(getFixture('hubs/get_hubs_id')); diff --git a/test/fixtures/hubs/get_hub_document_blocks.json b/test/fixtures/hubs/get_hub_document_blocks.json new file mode 100644 index 00000000..a09e0d5a --- /dev/null +++ b/test/fixtures/hubs/get_hub_document_blocks.json @@ -0,0 +1,17 @@ +{ + "entries": [ + { + "id": "block_1", + "type": "section_title", + "parent_id": "page_1", + "fragment": "Goals" + }, + { + "id": "block_2", + "type": "item_list", + "parent_id": "page_1" + } + ], + "type": "document_blocks", + "limit": 2 +} diff --git a/test/fixtures/hubs/get_hub_document_pages.json b/test/fixtures/hubs/get_hub_document_pages.json new file mode 100644 index 00000000..d90c264f --- /dev/null +++ b/test/fixtures/hubs/get_hub_document_pages.json @@ -0,0 +1,17 @@ +{ + "entries": [ + { + "id": "page_1", + "type": "page", + "title_fragment": "Overview" + }, + { + "id": "page_2", + "type": "page", + "parent_id": "page_1", + "title_fragment": "Launch Plan" + } + ], + "type": "document_pages", + "limit": 2 +}