confluence.js 2.0.0 → 2.1.0

package/src/api/contentBody.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class ContentBody {
@@ -20,6 +20,8 @@ export class ContentBody {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: If request specifies 'contentIdContext',
    * 'View' permission for the space, and permission to view the content.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async convertContentBody<T = Models.ContentBody>(
     parameters: Parameters.ConvertContentBody,
@@ -38,6 +40,8 @@ export class ContentBody {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: If request specifies 'contentIdContext',
    * 'View' permission for the space, and permission to view the content.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async convertContentBody<T = Models.ContentBody>(
     parameters: Parameters.ConvertContentBody,
@@ -72,7 +76,9 @@ export class ContentBody {
    *
    * Supported conversions:
    *
-   * - Storage: export_view
+   * - Atlas_doc_format: editor, export_view, storage, styled_view, view
+   * - Storage: atlas_doc_format, editor, export_view, styled_view, view
+   * - Editor: storage
    *
    * No other conversions are supported at the moment. Once a conversion is completed, it will be available for 5
    * minutes at the result endpoint.
@@ -90,7 +96,9 @@ export class ContentBody {
    *
    * Supported conversions:
    *
-   * - Storage: export_view
+   * - Atlas_doc_format: editor, export_view, storage, styled_view, view
+   * - Storage: atlas_doc_format, editor, export_view, styled_view, view
+   * - Editor: storage
    *
    * No other conversions are supported at the moment. Once a conversion is completed, it will be available for 5
    * minutes at the result endpoint.
@@ -127,8 +135,8 @@ export class ContentBody {
   }
 
   /**
-   * Returns the Asynchronous Content Body for the corresponding asyncId if the task is complete or returns the status
-   * of the task.
+   * Returns the asynchronous content body for the corresponding id if the task is complete or returns the status of the
+   * task.
    *
    * After the task is completed, the result can be obtained for 5 minutes, or until an identical conversion request is
    * made again, with allowCache query param set to false.
@@ -141,8 +149,8 @@ export class ContentBody {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Returns the Asynchronous Content Body for the corresponding asyncId if the task is complete or returns the status
-   * of the task.
+   * Returns the asynchronous content body for the corresponding id if the task is complete or returns the status of the
+   * task.
    *
    * After the task is completed, the result can be obtained for 5 minutes, or until an identical conversion request is
    * made again, with allowCache query param set to false.
@@ -165,4 +173,102 @@ export class ContentBody {
 
     return this.client.sendRequest(config, callback);
   }
+
+  /**
+   * Returns the content body for the corresponding `asyncId` of a completed conversion task. If the task is not
+   * completed, the task status is returned instead.
+   *
+   * Once a conversion task is completed, the result can be obtained for up to 5 minutes, or until an identical
+   * conversion request is made again with the `allowCache` parameter set to false.
+   *
+   * Note that there is a maximum limit of 50 task results per request to this endpoint.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
+   * ('Can use' global permission).
+   */
+  async bulkAsyncConvertContentBodyResponse<T = Models.AsyncContentBody[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyResponse,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Returns the content body for the corresponding `asyncId` of a completed conversion task. If the task is not
+   * completed, the task status is returned instead.
+   *
+   * Once a conversion task is completed, the result can be obtained for up to 5 minutes, or until an identical
+   * conversion request is made again with the `allowCache` parameter set to false.
+   *
+   * Note that there is a maximum limit of 50 task results per request to this endpoint.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to access the Confluence site
+   * ('Can use' global permission).
+   */
+  async bulkAsyncConvertContentBodyResponse<T = Models.AsyncContentBody[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyResponse,
+    callback?: never,
+  ): Promise<T>;
+  async bulkAsyncConvertContentBodyResponse<T = Models.AsyncContentBody[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyResponse,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/api/contentbody/convert/async/bulk/tasks',
+      method: 'GET',
+      params: {
+        ids: parameters.ids,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
+
+  /**
+   * Asynchronously converts content bodies from one format to another format in bulk. Use the Content body REST API to
+   * get the status of conversion tasks. Note that there is a maximum limit of 10 conversions per request to this
+   * endpoint.
+   *
+   * Supported conversions:
+   *
+   * - Storage: editor, export_view, styled_view, view
+   * - Editor: storage
+   *
+   * Once a conversion task is completed, it is available for polling for up to 5 minutes.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
+   * permission to view the content if the `spaceKeyContext` or `contentIdContext` are present.
+   */
+  async bulkAsyncConvertContentBodyRequest<T = Models.AsyncId[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyRequest,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Asynchronously converts content bodies from one format to another format in bulk. Use the Content body REST API to
+   * get the status of conversion tasks. Note that there is a maximum limit of 10 conversions per request to this
+   * endpoint.
+   *
+   * Supported conversions:
+   *
+   * - Storage: editor, export_view, styled_view, view
+   * - Editor: storage
+   *
+   * Once a conversion task is completed, it is available for polling for up to 5 minutes.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
+   * permission to view the content if the `spaceKeyContext` or `contentIdContext` are present.
+   */
+  async bulkAsyncConvertContentBodyRequest<T = Models.AsyncId[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyRequest,
+    callback?: never,
+  ): Promise<T>;
+  async bulkAsyncConvertContentBodyRequest<T = Models.AsyncId[]>(
+    parameters: Parameters.BulkAsyncConvertContentBodyRequest,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/api/contentbody/convert/async/bulk/tasks',
+      method: 'POST',
+      data: parameters,
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
 }

package/src/api/contentChildrenAndDescendants.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class ContentChildrenAndDescendants {
@@ -24,6 +24,8 @@ export class ContentChildrenAndDescendants {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentChildren<T = Models.ContentChildren>(
     parameters: Parameters.GetContentChildren,
@@ -46,6 +48,8 @@ export class ContentChildrenAndDescendants {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentChildren<T = Models.ContentChildren>(
     parameters: Parameters.GetContentChildren,
@@ -61,6 +65,8 @@ export class ContentChildrenAndDescendants {
       params: {
         expand: parameters.expand,
         parentVersion: parameters.parentVersion,
+        start: parameters.start,
+        limit: parameters.limit,
       },
     };
 
@@ -119,6 +125,8 @@ export class ContentChildrenAndDescendants {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentChildrenByType<T = Models.ContentArray>(
     parameters: Parameters.GetContentChildrenByType,
@@ -140,6 +148,8 @@ export class ContentChildrenAndDescendants {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentChildrenByType<T = Models.ContentArray>(
     parameters: Parameters.GetContentChildrenByType,
@@ -169,7 +179,11 @@ export class ContentChildrenAndDescendants {
    *
    * A piece of content has different types of descendants, depending on its type:
    *
-   * - `page`: descendant is `page`, `comment`, `attachment`
+   * - `page`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `whiteboard`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `database`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `embed`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `folder`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
    * - `blogpost`: descendant is `comment`, `attachment`
    * - `attachment`: descendant is `comment`
    * - `comment`: descendant is `attachment`
@@ -191,7 +205,11 @@ export class ContentChildrenAndDescendants {
    *
    * A piece of content has different types of descendants, depending on its type:
    *
-   * - `page`: descendant is `page`, `comment`, `attachment`
+   * - `page`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `whiteboard`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `database`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `embed`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `folder`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
    * - `blogpost`: descendant is `comment`, `attachment`
    * - `attachment`: descendant is `comment`
    * - `comment`: descendant is `attachment`
@@ -228,13 +246,20 @@ export class ContentChildrenAndDescendants {
    *
    * A piece of content has different types of descendants, depending on its type:
    *
-   * - `page`: descendant is `page`, `comment`, `attachment`
+   * - `page`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `whiteboard`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `database`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `embed`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `folder`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
    * - `blogpost`: descendant is `comment`, `attachment`
    * - `attachment`: descendant is `comment`
    * - `comment`: descendant is `attachment`
    *
    * Custom content types that are provided by apps can also be returned.
    *
+   * If the expand query parameter is used with the `body.export_view` and/or `body.styled_view` properties, then the
+   * query limit parameter will be restricted to a maximum value of 25.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
    */
@@ -249,13 +274,20 @@ export class ContentChildrenAndDescendants {
    *
    * A piece of content has different types of descendants, depending on its type:
    *
-   * - `page`: descendant is `page`, `comment`, `attachment`
+   * - `page`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `whiteboard`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `database`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `embed`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
+   * - `folder`: descendant is `page`, `whiteboard`, `database`, `embed`, `folder`, `comment`, `attachment`
    * - `blogpost`: descendant is `comment`, `attachment`
    * - `attachment`: descendant is `comment`
    * - `comment`: descendant is `attachment`
    *
    * Custom content types that are provided by apps can also be returned.
    *
+   * If the expand query parameter is used with the `body.export_view` and/or `body.styled_view` properties, then the
+   * query limit parameter will be restricted to a maximum value of 25.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
    */
@@ -329,6 +361,7 @@ export class ContentChildrenAndDescendants {
    *
    * - `space`: page will be copied to the specified space as a root page on the space
    * - `parent_page`: page will be copied as a child of the specified parent page
+   * - `parent_content`: page will be copied as a child of the specified parent content
    * - `existing_page`: page will be copied and replace the specified page
    *
    * By default, the following objects are expanded: `space`, `history`, `version`.
@@ -344,6 +377,7 @@ export class ContentChildrenAndDescendants {
    *
    * - `space`: page will be copied to the specified space as a root page on the space
    * - `parent_page`: page will be copied as a child of the specified parent page
+   * - `parent_content`: page will be copied as a child of the specified parent content
    * - `existing_page`: page will be copied and replace the specified page
    *
    * By default, the following objects are expanded: `space`, `history`, `version`.

package/src/api/contentComments.ts

@@ -4,6 +4,7 @@ import type { Callback } from '../callback';
 import type { Client } from '../clients';
 import type { RequestConfig } from '../requestConfig';
 
+/** @deprecated Will be removed in next major version. */
 export class ContentComments {
   constructor(private client: Client) {}
 
@@ -12,6 +13,8 @@ export class ContentComments {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentComments<T = Models.ContentArray>(
     parameters: Parameters.GetContentComments,
@@ -22,6 +25,8 @@ export class ContentComments {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space, and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getContentComments<T = Models.ContentArray>(
     parameters: Parameters.GetContentComments,

package/src/api/contentLabels.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class ContentLabels {
@@ -12,6 +12,8 @@ export class ContentLabels {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getLabelsForContent<T = Models.LabelArray>(
     parameters: Parameters.GetLabelsForContent,
@@ -22,6 +24,8 @@ export class ContentLabels {
    *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: 'View' permission for the space and
    * permission to view the content if it is a page.
+   *
+   * @deprecated Will be removed in next major version.
    */
   async getLabelsForContent<T = Models.LabelArray>(
     parameters: Parameters.GetLabelsForContent,
@@ -91,8 +95,9 @@ export class ContentLabels {
   }
 
   /**
-   * Removes a label from a piece of content. This is similar to [Remove label from
-   * content](#api-content-id-label-label-delete) except that the label name is specified via a query parameter.
+   * Removes a label from a piece of content. Labels can't be deleted from archived content. This is similar to [Remove
+   * label from content](#api-content-id-label-label-delete) except that the label name is specified via a query
+   * parameter.
    *
    * Use this method if the label name has "/" characters, as [Remove label from content using query
    * parameter](#api-content-id-label-delete) does not accept "/" characters for the label name.
@@ -104,8 +109,9 @@ export class ContentLabels {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Removes a label from a piece of content. This is similar to [Remove label from
-   * content](#api-content-id-label-label-delete) except that the label name is specified via a query parameter.
+   * Removes a label from a piece of content. Labels can't be deleted from archived content. This is similar to [Remove
+   * label from content](#api-content-id-label-label-delete) except that the label name is specified via a query
+   * parameter.
    *
    * Use this method if the label name has "/" characters, as [Remove label from content using query
    * parameter](#api-content-id-label-delete) does not accept "/" characters for the label name.
@@ -132,8 +138,9 @@ export class ContentLabels {
   }
 
   /**
-   * Removes a label from a piece of content. This is similar to [Remove label from content using query
-   * parameter](#api-content-id-label-delete) except that the label name is specified via a path parameter.
+   * Removes a label from a piece of content. Labels can't be deleted from archived content. This is similar to [Remove
+   * label from content using query parameter](#api-content-id-label-delete) except that the label name is specified via
+   * a path parameter.
    *
    * Use this method if the label name does not have "/" characters, as the path parameter does not accept "/"
    * characters for security reasons. Otherwise, use [Remove label from content using query
@@ -146,8 +153,9 @@ export class ContentLabels {
     callback: Callback<T>,
   ): Promise<void>;
   /**
-   * Removes a label from a piece of content. This is similar to [Remove label from content using query
-   * parameter](#api-content-id-label-delete) except that the label name is specified via a path parameter.
+   * Removes a label from a piece of content. Labels can't be deleted from archived content. This is similar to [Remove
+   * label from content using query parameter](#api-content-id-label-delete) except that the label name is specified via
+   * a path parameter.
    *
    * Use this method if the label name does not have "/" characters, as the path parameter does not accept "/"
    * characters for security reasons. Otherwise, use [Remove label from content using query

package/src/api/contentMacroBody.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class ContentMacroBody {
@@ -16,10 +16,23 @@ export class ContentMacroBody {
    * '50884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is
    * only modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */
@@ -36,10 +49,23 @@ export class ContentMacroBody {
    * '50884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is
    * only modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */
@@ -68,10 +94,23 @@ export class ContentMacroBody {
    * '50884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is
    * only modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */
@@ -88,10 +127,23 @@ export class ContentMacroBody {
    * '50884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is
    * only modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */
@@ -125,10 +177,23 @@ export class ContentMacroBody {
    * '884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is only
    * modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */
@@ -145,10 +210,23 @@ export class ContentMacroBody {
    * '884bd9-0cb8-41d5-98be-f80943c14f96'. The ID is then persisted as new versions of content are created, and is only
    * modified by Confluence if there are conflicting IDs.
    *
+   * For Forge macros, the value for macro ID is the "local ID" of that particular ADF node. This value can be retrieved
+   * either client-side by calling view.getContext() and accessing "localId" on the resulting object, or server-side by
+   * examining the "local-id" parameter node inside the "parameters" node.
+   *
+   * Note that there are other attributes named "local-id", but only this particular one is used to store the macro ID.
+   *
+   * Example: <ac:adf-node type="extension"> <ac:adf-attribute
+   * key="extension-type">com.atlassian.ecosystem</ac:adf-attribute> <ac:adf-attribute key="parameters">
+   * <ac:adf-parameter key="local-id">e9c4aa10-73fa-417c-888d-48c719ae4165</ac:adf-parameter> </ac:adf-parameter>
+   * </ac:adf-node>
+   *
    * Note, to preserve backwards compatibility this resource will also match on the hash of the macro body, even if a
    * macro ID is found. This check will eventually become redundant, as macro IDs are generated for pages and
    * transparently propagate out to all instances.
    *
+   * This backwards compatibility logic does not apply to Forge macros; those can only be retrieved by their ID.
+   *
    * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to view the content that the
    * macro is in.
    */

package/src/api/contentPermissions.ts

@@ -1,7 +1,7 @@
 import type * as Models from './models';
 import type * as Parameters from './parameters';
-import type { Callback } from '../callback';
 import type { Client } from '../clients';
+import type { Callback } from '../callback';
 import type { RequestConfig } from '../requestConfig';
 
 export class ContentPermissions {