feat: Add --raw-json flag and fix --json output (#669)

arjankowski · web-flow · commit ee6d61d576e5 · 2026-04-22T15:46:11.000+02:00
diff --git a/docs/ai.md b/docs/ai.md
@@ -16,7 +16,7 @@ Sends a request to supported LLMs using Box AI. This is intended for direct use,
 USAGE
   $ box ai:ask --prompt <value> --items <value>... [-t <value>] [--as-user <value>] [--no-color] [--json |
     --csv] [-s | --save-to-file-path <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q]
-    [--ai-agent <value>]
+    [--ai-agent <value>] [--raw-json | ]
 
 FLAGS
   -h, --help                       Show CLI help
@@ -36,6 +36,9 @@ FLAGS
       --json                       Output formatted JSON
       --no-color                   Turn off colors for logging
       --prompt=<value>             (required) The prompt for the AI request
+      --raw-json                   Output the raw API JSON response instead of the tsClient-normalized object fields.
+                                   Added as a non-breaking compatibility flag for users who need JSON field names to
+                                   match the API schema exactly. Implies --json.
       --save-to-file-path=<value>  Override default file path to save report
 
 DESCRIPTION
@@ -55,7 +58,7 @@ Sends an AI request to supported Large Language Models (LLMs) and extracts metad
 USAGE
   $ box ai:extract --prompt <value> --items <value>... [-t <value>] [--as-user <value>] [--no-color] [--json |
     --csv] [-s | --save-to-file-path <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q]
-    [--ai-agent <value>]
+    [--raw-json | ] [--ai-agent <value>]
 
 FLAGS
   -h, --help                       Show CLI help
@@ -76,6 +79,9 @@ FLAGS
       --json                       Output formatted JSON
       --no-color                   Turn off colors for logging
       --prompt=<value>             (required) The prompt provided to a Large Language Model (LLM) in the request.
+      --raw-json                   Output the raw API JSON response instead of the tsClient-normalized object fields.
+                                   Added as a non-breaking compatibility flag for users who need JSON field names to
+                                   match the API schema exactly. Implies --json.
       --save-to-file-path=<value>  Override default file path to save report
 
 DESCRIPTION
diff --git a/docs/integration-mappings.md b/docs/integration-mappings.md
@@ -233,8 +233,8 @@ List Teams integration mappings
 ```
 USAGE
   $ box integration-mappings:teams [-t <value>] [--as-user <value>] [--no-color] [--json | --csv] [-s | --save-to-file-path
-    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--max-items <value>] [--partner-item-id
-    <value>] [--partner-item-type <value>] [--box-item-id <value>] [--box-item-type <value>]
+    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--max-items <value>] [--raw-json | ]
+    [--partner-item-id <value>] [--partner-item-type <value>] [--box-item-id <value>] [--box-item-type <value>]
 
 FLAGS
   -h, --help                       Show CLI help
@@ -258,6 +258,9 @@ FLAGS
       --partner-item-id=<value>    ID of the mapped item, for which the mapping should be returned
       --partner-item-type=<value>  Mapped item type, for which the mapping should be returned, value is one of: channel,
                                    team
+      --raw-json                   Output the raw API JSON response instead of the tsClient-normalized object fields.
+                                   Added as a non-breaking compatibility flag for users who need JSON field names to
+                                   match the API schema exactly. Implies --json.
       --save-to-file-path=<value>  Override default file path to save report
 
 DESCRIPTION
@@ -358,8 +361,8 @@ List Teams integration mappings
 ```
 USAGE
   $ box integration-mappings:teams:list [-t <value>] [--as-user <value>] [--no-color] [--json | --csv] [-s | --save-to-file-path
-    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--max-items <value>] [--partner-item-id
-    <value>] [--partner-item-type <value>] [--box-item-id <value>] [--box-item-type <value>]
+    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--max-items <value>] [--raw-json | ]
+    [--partner-item-id <value>] [--partner-item-type <value>] [--box-item-id <value>] [--box-item-type <value>]
 
 FLAGS
   -h, --help                       Show CLI help
@@ -383,6 +386,9 @@ FLAGS
       --partner-item-id=<value>    ID of the mapped item, for which the mapping should be returned
       --partner-item-type=<value>  Mapped item type, for which the mapping should be returned, value is one of: channel,
                                    team
+      --raw-json                   Output the raw API JSON response instead of the tsClient-normalized object fields.
+                                   Added as a non-breaking compatibility flag for users who need JSON field names to
+                                   match the API schema exactly. Implies --json.
       --save-to-file-path=<value>  Override default file path to save report
 
 DESCRIPTION
@@ -404,7 +410,7 @@ Update Teams integration mapping
 ```
 USAGE
   $ box integration-mappings:teams:update ID [-t <value>] [--as-user <value>] [--no-color] [--json | --csv] [-s | --save-to-file-path
-    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--box-item-id <value>]
+    <value>] [--fields <value>] [--bulk-file-path <value>] [-h] [-v] [-y] [-q] [--raw-json | ] [--box-item-id <value>]
 
 ARGUMENTS
   ID  ID of an integration mapping
@@ -423,6 +429,9 @@ FLAGS
       --fields=<value>             Comma separated list of fields to show
       --json                       Output formatted JSON
       --no-color                   Turn off colors for logging
+      --raw-json                   Output the raw API JSON response instead of the tsClient-normalized object fields.
+                                   Added as a non-breaking compatibility flag for users who need JSON field names to
+                                   match the API schema exactly. Implies --json.
       --save-to-file-path=<value>  Override default file path to save report
 
 DESCRIPTION
diff --git a/src/box-command.js b/src/box-command.js
@@ -1187,6 +1187,44 @@ class BoxCommand extends Command {
 		return client;
 	}
 
+	/**
+	 * Returns true when raw API JSON output was requested.
+	 *
+	 * @returns {boolean} True if raw JSON output should be used
+	 * @private
+	 */
+	_wantsRawJsonOutput() {
+		return Boolean(this.flags && this.flags['raw-json']);
+	}
+
+	/**
+	 * Preserves default output behavior while adding raw JSON support.
+	 *
+	 * The generated TypeScript client can expose response objects with normalized
+	 * field names that do not match the original API schema. That behavior was
+	 * introduced as newer commands moved to `tsClient`. To fix the JSON output
+	 * shape without a breaking change, commands that support `--raw-json` use this
+	 * wrapper on the top-level response object before calling `output()`.
+	 *
+	 * @param {*} content The content to potentially replace with rawData
+	 * @returns {*} The content to send to output formatting
+	 */
+	getOutputContentWithRawJsonSupport(content) {
+		if (typeof content === 'object' && content !== null) {
+			if (this._wantsRawJsonOutput()) {
+				return content.rawData ?? content;
+			}
+
+			if (Object.hasOwn(content, 'rawData')) {
+				const output = { ...content };
+				delete output.rawData;
+				return output;
+			}
+		}
+
+		return content;
+	}
+
 	/**
 	 * Format data for output to stdout
 	 * @param {*} content The content to output
@@ -1323,7 +1361,11 @@ class BoxCommand extends Command {
 			}
 
 			const page = await fetchPage(pageQueryParams);
-			const pageEntries = page.entries || [];
+			const rawPage =
+				typeof page?.rawData === 'object' && page.rawData !== null
+					? page.rawData
+					: page;
+			const pageEntries = rawPage.entries || page.entries || [];
 			entries.push(...pageEntries);
 			remaining -= pageEntries.length;
 			marker = page.nextMarker || page.next_marker;
@@ -1393,6 +1435,12 @@ class BoxCommand extends Command {
 			return 'json';
 		}
 
+		// Raw API payloads are only intended for JSON output, so `--raw-json`
+		// implicitly promotes the format to JSON without changing default behavior.
+		if (this._wantsRawJsonOutput()) {
+			return 'json';
+		}
+
 		if (this.flags.csv) {
 			return 'csv';
 		}
@@ -2214,6 +2262,14 @@ BoxCommand.flags = {
 	}),
 };
 
+BoxCommand.rawJsonFlags = Object.freeze({
+	'raw-json': Flags.boolean({
+		description:
+			'Output the raw API JSON response instead of the tsClient-normalized object fields. Added as a non-breaking compatibility flag for users who need JSON field names to match the API schema exactly. Implies --json.',
+		exclusive: ['csv'],
+	}),
+});
+
 BoxCommand.minFlags = _.pick(BoxCommand.flags, [
 	'no-color',
 	'help',
diff --git a/src/commands/ai/ask.js b/src/commands/ai/ask.js
@@ -23,8 +23,7 @@ class AiAskCommand extends BoxCommand {
 		}
 
 		let answer = await this.tsClient.ai.createAiAsk(options);
-		delete answer.rawData;
-		await this.output(answer);
+		await this.output(this.getOutputContentWithRawJsonSupport(answer));
 	}
 }
 
@@ -96,6 +95,7 @@ AiAskCommand.flags = {
 			}
 		},
 	}),
+	...BoxCommand.rawJsonFlags,
 };
 
 module.exports = AiAskCommand;
diff --git a/src/commands/ai/extract.js b/src/commands/ai/extract.js
@@ -20,9 +20,7 @@ class AiExtractCommand extends BoxCommand {
 		}
 
 		let answer = await this.tsClient.ai.createAiExtract(options);
-
-		delete answer.rawData;
-		await this.output(answer);
+		await this.output(this.getOutputContentWithRawJsonSupport(answer));
 	}
 }
 
@@ -37,6 +35,7 @@ AiExtractCommand._endpoint = 'post_ai_extract';
 // Flags definition
 AiExtractCommand.flags = {
 	...BoxCommand.flags,
+	...BoxCommand.rawJsonFlags,
 	prompt: Flags.string({
 		required: true,
 		description:
diff --git a/src/commands/hubs/collaborations/create.js b/src/commands/hubs/collaborations/create.js
@@ -46,8 +46,7 @@ class HubsCreateCollaborationCommand extends BoxCommand {
 			await this.tsClient.hubCollaborations.createHubCollaborationV2025R0(
 				requestBody
 			);
-		delete collaboration.rawData;
-		await this.output(collaboration);
+		await this.output(collaboration.rawData ?? collaboration);
 	}
 }
 HubsCreateCollaborationCommand.aliases = ['hubs:collaborations:add'];
diff --git a/src/commands/hubs/collaborations/get.js b/src/commands/hubs/collaborations/get.js
@@ -10,8 +10,7 @@ class HubsGetCollaborationCommand extends BoxCommand {
 			await this.tsClient.hubCollaborations.getHubCollaborationByIdV2025R0(
 				args.id
 			);
-		delete collaboration.rawData;
-		await this.output(collaboration);
+		await this.output(collaboration.rawData ?? collaboration);
 	}
 }
 
diff --git a/src/commands/hubs/collaborations/update.js b/src/commands/hubs/collaborations/update.js
@@ -15,8 +15,7 @@ class HubsUpdateCollaborationCommand extends BoxCommand {
 					role: flags.role,
 				}
 			);
-		delete collaboration.rawData;
-		await this.output(collaboration);
+		await this.output(collaboration.rawData ?? collaboration);
 	}
 }
 
diff --git a/src/commands/hubs/copy.js b/src/commands/hubs/copy.js
@@ -17,8 +17,7 @@ class HubsCopyCommand extends BoxCommand {
 		}
 
 		const hub = await this.tsClient.hubs.copyHubV2025R0(args.id, requestBody);
-		delete hub.rawData;
-		await this.output(hub);
+		await this.output(hub.rawData ?? hub);
 	}
 }
 
diff --git a/src/commands/hubs/create.js b/src/commands/hubs/create.js
@@ -16,8 +16,7 @@ class HubsCreateCommand extends BoxCommand {
 		}
 
 		const hub = await this.tsClient.hubs.createHubV2025R0(requestBody);
-		delete hub.rawData;
-		await this.output(hub);
+		await this.output(hub.rawData ?? hub);
 	}
 }
 
diff --git a/src/commands/hubs/get.js b/src/commands/hubs/get.js
@@ -7,8 +7,7 @@ class HubsGetCommand extends BoxCommand {
 	async run() {
 		const { args } = await this.parse(HubsGetCommand);
 		const hub = await this.tsClient.hubs.getHubByIdV2025R0(args.id);
-		delete hub.rawData;
-		await this.output(hub);
+		await this.output(hub.rawData ?? hub);
 	}
 }
 
diff --git a/src/commands/hubs/items/manage.js b/src/commands/hubs/items/manage.js
@@ -51,8 +51,7 @@ class HubsManageItemsCommand extends BoxCommand {
 			args.id,
 			{ operations }
 		);
-		delete response.rawData;
-		await this.output(response);
+		await this.output(response.rawData ?? response);
 	}
 }
 
diff --git a/src/commands/hubs/update.js b/src/commands/hubs/update.js
@@ -42,8 +42,7 @@ class HubsUpdateCommand extends BoxCommand {
 			args.id,
 			requestBody
 		);
-		delete hub.rawData;
-		await this.output(hub);
+		await this.output(hub.rawData ?? hub);
 	}
 }
 
diff --git a/src/commands/integration-mappings/teams/index.js b/src/commands/integration-mappings/teams/index.js
@@ -26,8 +26,9 @@ class IntegrationMappingsTeamsListCommand extends BoxCommand {
 			await this.tsClient.integrationMappings.getTeamsIntegrationMapping(
 				options
 			);
-		delete teamsIntegrationMappings.rawData;
-		await this.output(teamsIntegrationMappings);
+		await this.output(
+			this.getOutputContentWithRawJsonSupport(teamsIntegrationMappings)
+		);
 	}
 }
 
@@ -47,6 +48,7 @@ IntegrationMappingsTeamsListCommand._endpoint =
 IntegrationMappingsTeamsListCommand.flags = {
 	...BoxCommand.flags,
 	...PaginationUtilities.flags,
+	...BoxCommand.rawJsonFlags,
 	'partner-item-id': Flags.string({
 		hidden: false,
 		description:
diff --git a/src/commands/integration-mappings/teams/update.js b/src/commands/integration-mappings/teams/update.js
@@ -24,8 +24,9 @@ class IntegrationMappingsTeamsUpdateCommand extends BoxCommand {
 					requestBody: body,
 				}
 			);
-		delete integrationMapping.rawData;
-		await this.output(integrationMapping);
+		await this.output(
+			this.getOutputContentWithRawJsonSupport(integrationMapping)
+		);
 	}
 }
 
@@ -39,6 +40,7 @@ IntegrationMappingsTeamsUpdateCommand._endpoint =
 
 IntegrationMappingsTeamsUpdateCommand.flags = {
 	...BoxCommand.flags,
+	...BoxCommand.rawJsonFlags,
 	'box-item-id': Flags.string({
 		description: 'ID of the mapped folder',
 	}),
diff --git a/test/commands/ai.test.js b/test/commands/ai.test.js
@@ -82,6 +82,24 @@ describe('AI', function () {
 		const fixture = getFixture('ai/post_ai_ask_response');
 		const yamlFixture = getFixture('ai/post_ai_ask_response_yaml.txt');
 
+		test.nock(TEST_API_ROOT, (api) =>
+			api
+				.post('/2.0/ai/ask', expectedRequestBody)
+				.reply(200, expectedResponseBody)
+		)
+			.stdout()
+			.command([
+				'ai:ask',
+				'--items=content=one,two,three,id=12345,type=file',
+				'--prompt',
+				'What is the status of this document?',
+				'--raw-json',
+				'--token=test',
+			])
+			.it('should output the raw response when --raw-json is passed', (context) => {
+				assert.deepEqual(JSON.parse(context.stdout), expectedResponseBody);
+			});
+
 		test.nock(TEST_API_ROOT, (api) =>
 			api
 				.post('/2.0/ai/ask', expectedRequestBody)
@@ -301,6 +319,29 @@ describe('AI', function () {
 		const fixture = getFixture('ai/post_ai_extract_response');
 		const yamlFixture = getFixture('ai/post_ai_extract_response_yaml.txt');
 
+		test.nock(TEST_API_ROOT, (api) => {
+			api.post('/2.0/ai/extract', expectedRequestBody).reply(
+				200,
+				expectedResponseBody
+			);
+		})
+			.stdout()
+			.command([
+				'ai:extract',
+				'--items=content=one,two,three,id=12345,type=file',
+				'--prompt',
+				'firstName, lastName, location, yearOfBirth, company',
+				'--raw-json',
+				'--token=test',
+			])
+
+			.it(
+				'should output the raw response when --raw-json is passed',
+				(context) => {
+					assert.deepEqual(JSON.parse(context.stdout), expectedResponseBody);
+				}
+			);
+
 		test.nock(TEST_API_ROOT, (api) => {
 			api.post('/2.0/ai/extract', expectedRequestBody).reply(
 				200,
diff --git a/test/commands/hubs.test.js b/test/commands/hubs.test.js
diff --git a/test/commands/integration-mappings.test.js b/test/commands/integration-mappings.test.js

Original file line number	Diff line number	Diff line change
`@@ -23,8 +23,7 @@ class AiAskCommand extends BoxCommand {`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	`let answer = await this.tsClient.ai.createAiAsk(options);`
`26`		`- delete answer.rawData;`
`27`		`- await this.output(answer);`
	`26`	`+ await this.output(this.getOutputContentWithRawJsonSupport(answer));`
`28`	`27`	`}`
`29`	`28`	`}`
`30`	`29`
`@@ -96,6 +95,7 @@ AiAskCommand.flags = {`
`96`	`95`	`}`
`97`	`96`	`},`
`98`	`97`	`}),`
	`98`	`+ ...BoxCommand.rawJsonFlags,`
`99`	`99`	`};`
`100`	`100`
`101`	`101`	`module.exports = AiAskCommand;`
Original file line number	Diff line number	Diff line change
`@@ -20,9 +20,7 @@ class AiExtractCommand extends BoxCommand {`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`let answer = await this.tsClient.ai.createAiExtract(options);`
`23`		`-`
`24`		`- delete answer.rawData;`
`25`		`- await this.output(answer);`
	`23`	`+ await this.output(this.getOutputContentWithRawJsonSupport(answer));`
`26`	`24`	`}`
`27`	`25`	`}`
`28`	`26`
`@@ -37,6 +35,7 @@ AiExtractCommand._endpoint = 'post_ai_extract';`
`37`	`35`	`// Flags definition`
`38`	`36`	`AiExtractCommand.flags = {`
`39`	`37`	`...BoxCommand.flags,`
	`38`	`+ ...BoxCommand.rawJsonFlags,`
`40`	`39`	`prompt: Flags.string({`
`41`	`40`	`required: true,`
`42`	`41`	`description:`
Original file line number	Diff line number	Diff line change
`@@ -46,8 +46,7 @@ class HubsCreateCollaborationCommand extends BoxCommand {`
`46`	`46`	`await this.tsClient.hubCollaborations.createHubCollaborationV2025R0(`
`47`	`47`	`requestBody`
`48`	`48`	`);`
`49`		`- delete collaboration.rawData;`
`50`		`- await this.output(collaboration);`
	`49`	`+ await this.output(collaboration.rawData ?? collaboration);`
`51`	`50`	`}`
`52`	`51`	`}`
`53`	`52`	`HubsCreateCollaborationCommand.aliases = ['hubs:collaborations:add'];`
Original file line number	Diff line number	Diff line change
`@@ -10,8 +10,7 @@ class HubsGetCollaborationCommand extends BoxCommand {`
`10`	`10`	`await this.tsClient.hubCollaborations.getHubCollaborationByIdV2025R0(`
`11`	`11`	`args.id`
`12`	`12`	`);`
`13`		`- delete collaboration.rawData;`
`14`		`- await this.output(collaboration);`
	`13`	`+ await this.output(collaboration.rawData ?? collaboration);`
`15`	`14`	`}`
`16`	`15`	`}`
`17`	`16`
Original file line number	Diff line number	Diff line change
`@@ -15,8 +15,7 @@ class HubsUpdateCollaborationCommand extends BoxCommand {`
`15`	`15`	`role: flags.role,`
`16`	`16`	`}`
`17`	`17`	`);`
`18`		`- delete collaboration.rawData;`
`19`		`- await this.output(collaboration);`
	`18`	`+ await this.output(collaboration.rawData ?? collaboration);`
`20`	`19`	`}`
`21`	`20`	`}`
`22`	`21`
Original file line number	Diff line number	Diff line change
`@@ -17,8 +17,7 @@ class HubsCopyCommand extends BoxCommand {`
`17`	`17`	`}`
`18`	`18`
`19`	`19`	`const hub = await this.tsClient.hubs.copyHubV2025R0(args.id, requestBody);`
`20`		`- delete hub.rawData;`
`21`		`- await this.output(hub);`
	`20`	`+ await this.output(hub.rawData ?? hub);`
`22`	`21`	`}`
`23`	`22`	`}`
`24`	`23`
Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,7 @@ class HubsCreateCommand extends BoxCommand {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`const hub = await this.tsClient.hubs.createHubV2025R0(requestBody);`
`19`		`- delete hub.rawData;`
`20`		`- await this.output(hub);`
	`19`	`+ await this.output(hub.rawData ?? hub);`
`21`	`20`	`}`
`22`	`21`	`}`
`23`	`22`