Add reports endpoints for phase 2.

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [X.X.X] - Unreleased
 
+### Added
+- Added support for GET /2.0/reports/{reportId}/scope endpoint (`listReportScope`)
+- Added support for GET /2.0/reports/{reportId}/columns endpoint (`listReportColumns`)
+- Added support for GET /2.0/reports/{reportId}/columns/{columnVirtualId} endpoint (`getReportColumn`)
+- Added support for PUT /2.0/reports/{reportId}/columns/{columnVirtualId} endpoint (`updateReportColumn`)
+- Added support for DELETE /2.0/reports/{reportId}/columns/{columnVirtualId} endpoint (`deleteReportColumn`)
+- Added support for GET /2.0/reports/{reportId}/definition endpoint (`getReportDefinition`)
+
 ### Deprecated
 
 - Deprecated `Event.objectId`; use `Event.objectIdStr` instead. `objectId` is numeric only and contains -1 for non-numeric identifiers. It is not scheduled for removal.

lib/reports/index.ts

@@ -26,6 +26,17 @@ import type {
   CreateReportOptions,
   CreateReportResponse,
   GetReportPathOptions,
+  ListReportScopeOptions,
+  ListReportScopeResponse,
+  ListReportColumnsOptions,
+  ListReportColumnsResponse,
+  GetReportColumnOptions,
+  ReportColumn,
+  UpdateReportColumnOptions,
+  UpdateReportColumnResponse,
+  DeleteReportColumnOptions,
+  GetReportDefinitionOptions,
+  ReportDefinition,
 } from './types';
 import type { ReportPathNode } from './types';
 import * as constants from '../utils/constants';
@@ -150,6 +161,60 @@ export function create(options: CreateOptions): ReportsApi {
     return requestor.get({ ...optionsToSend, ...urlOptions, ...getOptions }, callback);
   };
 
+  const listReportScope = (
+    getOptions: ListReportScopeOptions,
+    callback?: RequestCallback<ListReportScopeResponse>
+  ): Promise<ListReportScopeResponse> => {
+    const urlOptions = { url: options.apiUrls.reports + '/' + getOptions.reportId + '/scope' };
+    return requestor.get({ ...optionsToSend, ...urlOptions, ...getOptions }, callback);
+  };
+
+  const listReportColumns = (
+    getOptions: ListReportColumnsOptions,
+    callback?: RequestCallback<ListReportColumnsResponse>
+  ): Promise<ListReportColumnsResponse> => {
+    const urlOptions = { url: options.apiUrls.reports + '/' + getOptions.reportId + '/columns' };
+    return requestor.get({ ...optionsToSend, ...urlOptions, ...getOptions }, callback);
+  };
+
+  const getReportColumn = (
+    getOptions: GetReportColumnOptions,
+    callback?: RequestCallback<ReportColumn>
+  ): Promise<ReportColumn> => {
+    const urlOptions = {
+      url: options.apiUrls.reports + '/' + getOptions.reportId + '/columns/' + getOptions.columnVirtualId,
+    };
+    return requestor.get({ ...optionsToSend, ...urlOptions, ...getOptions }, callback);
+  };
+
+  const updateReportColumn = (
+    putOptions: UpdateReportColumnOptions,
+    callback?: RequestCallback<UpdateReportColumnResponse>
+  ): Promise<UpdateReportColumnResponse> => {
+    const urlOptions = {
+      url: options.apiUrls.reports + '/' + putOptions.reportId + '/columns/' + putOptions.columnVirtualId,
+    };
+    return requestor.put({ ...optionsToSend, ...urlOptions, ...putOptions }, callback);
+  };
+
+  const deleteReportColumn = (
+    deleteOptions: DeleteReportColumnOptions,
+    callback?: RequestCallback<BaseResponseStatus>
+  ): Promise<BaseResponseStatus> => {
+    const urlOptions = {
+      url: options.apiUrls.reports + '/' + deleteOptions.reportId + '/columns/' + deleteOptions.columnVirtualId,
+    };
+    return requestor.delete({ ...optionsToSend, ...urlOptions, ...deleteOptions }, callback);
+  };
+
+  const getReportDefinition = (
+    getOptions: GetReportDefinitionOptions,
+    callback?: RequestCallback<ReportDefinition>
+  ): Promise<ReportDefinition> => {
+    const urlOptions = { url: options.apiUrls.reports + '/' + getOptions.reportId + '/definition' };
+    return requestor.get({ ...optionsToSend, ...urlOptions, ...getOptions }, callback);
+  };
+
   return {
     listReports,
     getReport,
@@ -165,5 +230,11 @@ export function create(options: CreateOptions): ReportsApi {
     addReportColumns,
     createReport,
     getReportPath,
+    listReportScope,
+    listReportColumns,
+    getReportColumn,
+    updateReportColumn,
+    deleteReportColumn,
+    getReportDefinition,
   };
 }

lib/reports/types.ts

@@ -3,6 +3,8 @@
 import type { RequestCallback } from '../types/RequestCallback';
 import type { RequestOptions } from '../types/RequestOptions';
 import type { BaseResponseStatus } from '../types/BaseResponseStatus';
+import type { TokenPaginationQueryParameters } from '../types/TokenPaginationQueryParameters';
+import type { TokenPaginationResponse } from '../types/TokenPaginationResponse';
 import type { FailedItem } from '../types/FailedItem';
 import type { Attachment } from '../attachments/types';
 import type { Column } from '../columns/types';
@@ -451,6 +453,127 @@
    * ```
    */
   getReportPath: (options: GetReportPathOptions, callback?: RequestCallback<ReportPathNode>) => Promise<ReportPathNode>;
+
+  /**
+   * Gets the scope of a Report.
+   *
+   * @param options - {@link ListReportScopeOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link ListReportScopeResponse}\> - Optional callback function
+   * @returns Promise\<{@link ListReportScopeResponse}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `GET /reports/{reportId}/scope`
+   *
+   * @example
+   * ```typescript
+   * const scope = await client.reports.listReportScope({ reportId: 4583173393803140 });
+   * ```
+   */
+  listReportScope: (
+    options: ListReportScopeOptions,
+    callback?: RequestCallback<ListReportScopeResponse>
+  ) => Promise<ListReportScopeResponse>;
+
+  /**
+   * Gets the columns of a Report.
+   *
+   * @param options - {@link ListReportColumnsOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link ListReportColumnsResponse}\> - Optional callback function
+   * @returns Promise\<{@link ListReportColumnsResponse}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `GET /reports/{reportId}/columns`
+   *
+   * @example
+   * ```typescript
+   * const columns = await client.reports.listReportColumns({ reportId: 4583173393803140 });
+   * ```
+   */
+  listReportColumns: (
+    options: ListReportColumnsOptions,
+    callback?: RequestCallback<ListReportColumnsResponse>
+  ) => Promise<ListReportColumnsResponse>;
+
+  /**
+   * Gets a single column of a Report.
+   *
+   * @param options - {@link GetReportColumnOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link ReportColumn}\> - Optional callback function
+   * @returns Promise\<{@link ReportColumn}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `GET /reports/{reportId}/columns/{columnVirtualId}`
+   *
+   * @example
+   * ```typescript
+   * const column = await client.reports.getReportColumn({ reportId: 4583173393803140, columnVirtualId: 123 });
+   * ```
+   */
+  getReportColumn: (options: GetReportColumnOptions, callback?: RequestCallback<ReportColumn>) => Promise<ReportColumn>;
+
+  /**
+   * Updates a column of a Report.
+   *
+   * @param options - {@link UpdateReportColumnOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link UpdateReportColumnResponse}\> - Optional callback function
+   * @returns Promise\<{@link UpdateReportColumnResponse}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `PUT /reports/{reportId}/columns/{columnVirtualId}`
+   *
+   * @example
+   * ```typescript
+   * const result = await client.reports.updateReportColumn({
+   *   reportId: 4583173393803140,
+   *   columnVirtualId: 123,
+   *   body: { title: 'New Title', hidden: false }
+   * });
+   * ```
+   */
+  updateReportColumn: (
+    options: UpdateReportColumnOptions,
+    callback?: RequestCallback<UpdateReportColumnResponse>
+  ) => Promise<UpdateReportColumnResponse>;
+
+  /**
+   * Deletes a column from a Report.
+   *
+   * @param options - {@link DeleteReportColumnOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link BaseResponseStatus}\> - Optional callback function
+   * @returns Promise\<{@link BaseResponseStatus}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `DELETE /reports/{reportId}/columns/{columnVirtualId}`
+   *
+   * @example
+   * ```typescript
+   * const result = await client.reports.deleteReportColumn({ reportId: 4583173393803140, columnVirtualId: 123 });
+   * ```
+   */
+  deleteReportColumn: (
+    options: DeleteReportColumnOptions,
+    callback?: RequestCallback<BaseResponseStatus>
+  ) => Promise<BaseResponseStatus>;
+
+  /**
+   * Gets the definition of a Report.
+   *
+   * @param options - {@link GetReportDefinitionOptions} - Configuration options for the request
+   * @param callback - {@link RequestCallback}\<{@link ReportDefinition}\> - Optional callback function
+   * @returns Promise\<{@link ReportDefinition}\>
+   *
+   * @remarks
+   * It mirrors to the following Smartsheet REST API method: `GET /reports/{reportId}/definition`
+   *
+   * @example
+   * ```typescript
+   * const definition = await client.reports.getReportDefinition({ reportId: 4583173393803140 });
+   * ```
+   */
+  getReportDefinition: (
+    options: GetReportDefinitionOptions,
+    callback?: RequestCallback<ReportDefinition>
+  ) => Promise<ReportDefinition>;
 }
 
 // ============================================================================
@@ -1252,7 +1375,7 @@
    * For DATE objects, this would be a date string.
    * For CURRENT_USER, this represents the user identifier.
    */
-  value: string;
+  value?: string;
 }
 
 /**
@@ -1439,7 +1562,7 @@
   fill: string;
   /**
    * The prefix. Can include these date tokens:
    * - {DD}
    * - {MM}
    * - {YY}
    * - {YYYY}
@@ -1690,3 +1813,125 @@
    */
   reportId: number;
 }
+
+// ============================================================================
+// Get Report Scope
+// ============================================================================
+
+export interface ListReportScopeOptions extends RequestOptions<TokenPaginationQueryParameters, undefined> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+}
+
+export type ListReportScopeResponse = TokenPaginationResponse<ReportScopeAsset>;
+
+// ============================================================================
+// Get Report Columns
+// ============================================================================
+
+export interface ListReportColumnsQueryParameters extends TokenPaginationQueryParameters {
+  /**
+   * Compatibility level.
+   */
+  level?: number;
+}
+
+export interface ListReportColumnsOptions extends RequestOptions<ListReportColumnsQueryParameters, undefined> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+}
+
+export type ListReportColumnsResponse = TokenPaginationResponse<ReportColumn>;
+
+// ============================================================================
+// Get Report Column
+// ============================================================================
+
+export interface GetReportColumnQueryParameters {
+  /**
+   * Compatibility level.
+   */
+  level?: number;
+}
+
+export interface GetReportColumnOptions extends RequestOptions<GetReportColumnQueryParameters, undefined> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+  /**
+   * The virtual ID of the report column.
+   */
+  columnVirtualId: number;
+}
+
+// ============================================================================
+// Update Report Column
+// ============================================================================
+
+export interface UpdateReportColumnRequest {
+  /**
+   * Column title.
+   */
+  title?: string;
+  /**
+   * Column index or position.
+   */
+  index?: number;
+  /**
+   * Indicates whether the column is hidden.
+   */
+  hidden?: boolean;
+  /**
+   * Display width of the column in pixels.
+   */
+  width?: number;
+}
+
+export interface UpdateReportColumnOptions extends RequestOptions<undefined, UpdateReportColumnRequest> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+  /**
+   * The virtual ID of the report column.
+   */
+  columnVirtualId: number;
+}
+
+export interface UpdateReportColumnResponse extends BaseResponseStatus {
+  /**
+   * The updated report column.
+   */
+  result: ReportColumn;
+}
+
+// ============================================================================
+// Delete Report Column
+// ============================================================================
+
+export interface DeleteReportColumnOptions extends RequestOptions<undefined, undefined> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+  /**
+   * The virtual ID of the report column.
+   */
+  columnVirtualId: number;
+}
+
+// ============================================================================
+// Get Report Definition
+// ============================================================================
+
+export interface GetReportDefinitionOptions extends RequestOptions<undefined, undefined> {
+  /**
+   * Report ID.
+   */
+  reportId: number;
+}