datocms-plugin-sdk 0.3.1 → 0.3.5

package/dist/types/types.d.ts

@@ -10,19 +10,15 @@ export declare type MainNavigationTab = {
         pageId: string;
     };
     /**
-     * Expresses where you want to place the tab in the top-bar. If not specified,
-     * the tab will be placed after the standard tabs provided by DatoCMS itself.
+     * Expresses where you want to place the tab in the top-bar. If not specified, the tab
+     * will be placed after the standard tabs provided by DatoCMS itself.
      */
-    placement?: [
-        'before' | 'after',
-        'content' | 'mediaArea' | 'apiExplorer' | 'settings'
-    ];
+    placement?: ['before' | 'after', 'content' | 'mediaArea' | 'apiExplorer' | 'settings'];
     /**
-     * If different plugins specify the same `placement` for their tabs, they will
-     * be displayed by ascending `rank`. If you want to specify an explicit value
-     * for `rank`, make sure to offer a way for final users to customize it inside
-     * the plugin's settings form, otherwise the hardcoded value you choose might
-     * clash with the one of another plugin! *
+     * If different plugins specify the same `placement` for their tabs, they will be
+     * displayed by ascending `rank`. If you want to specify an explicit value for `rank`,
+     * make sure to offer a way for final users to customize it inside the plugin's settings
+     * form, otherwise the hardcoded value you choose might clash with the one of another plugin! *
      */
     rank?: number;
 };
@@ -38,9 +34,8 @@ export declare type SettingsAreaSidebarItem = {
     };
 };
 /**
- * The sidebar in the Settings Area presents a number of pages grouped by topic.
- * This object represents a new group to be added in the sideebar to the
- * standard ones DatoCMS provides.
+ * The sidebar in the Settings Area presents a number of pages grouped by topic. This
+ * object represents a new group to be added in the sideebar to the standard ones DatoCMS provides.
  */
 export declare type SettingsAreaSidebarItemGroup = {
     /** Label to be shown. Must be unique. */
@@ -48,26 +43,24 @@ export declare type SettingsAreaSidebarItemGroup = {
     /** The list of items it contains * */
     items: SettingsAreaSidebarItem[];
     /**
-     * Expresses where you want the group to be placed inside the sidebar. If not
-     * specified, the item will be placed after the standard items provided by
-     * DatoCMS itself.
+     * Expresses where you want the group to be placed inside the sidebar. If not specified,
+     * the item will be placed after the standard items provided by DatoCMS itself.
      */
     placement?: [
         'before' | 'after',
         ('environment' | 'project' | 'permissions' | 'webhooks' | 'deployment' | 'sso' | 'auditLog' | 'usage')
     ];
     /**
-     * If different plugins specify the same `placement` for their sections, they
-     * will be displayed by ascending `rank`. If you want to specify an explicit
-     * value for `rank`, make sure to offer a way for final users to customize it
-     * inside the plugin's settings form, otherwise the hardcoded value you choose
-     * might clash with the one of another plugin! *
+     * If different plugins specify the same `placement` for their sections, they will be
+     * displayed by ascending `rank`. If you want to specify an explicit value for `rank`,
+     * make sure to offer a way for final users to customize it inside the plugin's settings
+     * form, otherwise the hardcoded value you choose might clash with the one of another plugin! *
      */
     rank?: number;
 };
 /**
- * The sidebar in the Content Area presents a number of user-defined menu-items.
- * This object represents a new item to be added in the sidebar.
+ * The sidebar in the Content Area presents a number of user-defined menu-items. This
+ * object represents a new item to be added in the sidebar.
  */
 export declare type ContentAreaSidebarItem = {
     /** Label to be shown. Must be unique. */
@@ -79,44 +72,38 @@ export declare type ContentAreaSidebarItem = {
         pageId: string;
     };
     /**
-     * Expresses where you want the item to be placed inside the sidebar. If not
-     * specified, the item will be placed after the standard items provided by
-     * DatoCMS itself.
+     * Expresses where you want the item to be placed inside the sidebar. If not specified,
+     * the item will be placed after the standard items provided by DatoCMS itself.
      */
     placement?: ['before' | 'after', 'menuItems' | 'settings'];
     /**
-     * If different plugins specify the same `placement` for their panels, they
-     * will be displayed by ascending `rank`. If you want to specify an explicit
-     * value for `rank`, make sure to offer a way for final users to customize it
-     * inside the plugin's settings form, otherwise the hardcoded value you choose
-     * might clash with the one of another plugin! *
+     * If different plugins specify the same `placement` for their panels, they will be
+     * displayed by ascending `rank`. If you want to specify an explicit value for `rank`,
+     * make sure to offer a way for final users to customize it inside the plugin's settings
+     * form, otherwise the hardcoded value you choose might clash with the one of another plugin! *
      */
     rank?: number;
 };
 export declare type FieldExtensionType = 'editor' | 'addon';
 /**
- * Field extensions extend the basic functionality of DatoCMS when it comes to
- * presenting record's fields to the final user. Depending on the extension type
- * (`editor` or `addon`) they will be shown in different places of the interface.
+ * Field extensions extend the basic functionality of DatoCMS when it comes to presenting
+ * record's fields to the final user. Depending on the extension type (`editor` or
+ * `addon`) they will be shown in different places of the interface.
  */
 export declare type ManualFieldExtension = {
-    /**
-     * ID of field extension. Will be the first argument for the
-     * `renderFieldExtension` function
-     */
+    /** ID of field extension. Will be the first argument for the `renderFieldExtension` function */
     id: string;
     /** Name to be shown when editing fields */
     name: string;
     /**
-     * Type of field extension. An `editor` extension replaces the default field
-     * editor that DatoCMS provides, while an `addon` extension is placed
-     * underneath the field editor to provide additional info/behaviour. You can
-     * setup multiple field addons for every field.
+     * Type of field extension. An `editor` extension replaces the default field editor that
+     * DatoCMS provides, while an `addon` extension is placed underneath the field editor to
+     * provide additional info/behaviour. You can setup multiple field addons for every field.
      */
     type: FieldExtensionType;
     /**
-     * For `editor` extensions: moves the field to the sidebar of the record
-     * editing page, mimicking a sidebar panel
+     * For `editor` extensions: moves the field to the sidebar of the record editing page,
+     * mimicking a sidebar panel
      */
     asSidebarPanel?: boolean | {
         startOpen: boolean;
@@ -124,9 +111,8 @@ export declare type ManualFieldExtension = {
     /** The type of fields that the field extension in compatible with */
     fieldTypes: NonNullable<PluginAttributes['field_types']>;
     /**
-     * Whether this field extension needs some configuration options before being
-     * installed in a field or not. Will trigger the
-     * `renderManualFieldExtensionConfigScreen` and
+     * Whether this field extension needs some configuration options before being installed
+     * in a field or not. Will trigger the `renderManualFieldExtensionConfigScreen` and
      * `validateManualFieldExtensionParameters` methods
      */
     configurable?: boolean | {
@@ -141,32 +127,27 @@ export declare type ItemFormSidebarPanelPlacement = [
 ];
 /** A sidebar panel to be shown inside the record's editing page */
 export declare type ItemFormSidebarPanel = {
-    /**
-     * ID of the panel. Will be the first argument for the
-     * `renderItemFormSidebarPanel` function
-     */
+    /** ID of the panel. Will be the first argument for the `renderItemFormSidebarPanel` function */
     id: string;
     /** Label to be shown on the collapsible sidebar panel handle */
     label: string;
     /**
-     * An arbitrary configuration object that will be passed as the `parameters`
-     * property of the second argument of the `renderItemFormSidebarPanel` function
+     * An arbitrary configuration object that will be passed as the `parameters` property of
+     * the second argument of the `renderItemFormSidebarPanel` function
      */
     parameters?: Record<string, unknown>;
     /** Whether the sidebar panel will start open or collapsed */
     startOpen?: boolean;
     /**
-     * Expresses where you want the item to be placed inside the sidebar. If not
-     * specified, the item will be placed after the standard panels provided by
-     * DatoCMS itself.
+     * Expresses where you want the item to be placed inside the sidebar. If not specified,
+     * the item will be placed after the standard panels provided by DatoCMS itself.
      */
     placement?: ItemFormSidebarPanelPlacement;
     /**
-     * If multiple sidebar panels specify the same `placement`, they will be
-     * sorted by ascending `rank`. If you want to specify an explicit value for
-     * `rank`, make sure to offer a way for final users to customize it inside the
-     * plugin's settings form, otherwise the hardcoded value you choose might
-     * clash with the one of another plugin! *
+     * If multiple sidebar panels specify the same `placement`, they will be sorted by
+     * ascending `rank`. If you want to specify an explicit value for `rank`, make sure to
+     * offer a way for final users to customize it inside the plugin's settings form,
+     * otherwise the hardcoded value you choose might clash with the one of another plugin! *
      */
     rank?: number;
     /** The initial height to set for the iframe that will render the sidebar panel */
@@ -174,10 +155,7 @@ export declare type ItemFormSidebarPanel = {
 };
 /** A field editor/sidebar forced on a field */
 export declare type EditorOverride = {
-    /**
-     * ID of field extension. Will be the first argument for the
-     * `renderFieldExtension` function
-     */
+    /** ID of field extension. Will be the first argument for the `renderFieldExtension` function */
     id: string;
     /** Moves the field to the sidebar of the record editing page, mimicking a sidebar panel */
     asSidebarPanel?: boolean | {
@@ -185,16 +163,15 @@ export declare type EditorOverride = {
         placement?: ItemFormSidebarPanelPlacement;
     };
     /**
-     * An arbitrary configuration object that will be passed as the `parameters`
-     * property of the second argument of the `renderFieldExtension` function
+     * An arbitrary configuration object that will be passed as the `parameters` property of
+     * the second argument of the `renderFieldExtension` function
      */
     parameters?: Record<string, unknown>;
     /**
-     * If multiple plugins override a field, the one with the highest `rank` will
-     * win. If you want to specify an explicit value for `rank`, make sure to
-     * offer a way for final users to customize it inside the plugin's settings
-     * form, otherwise the hardcoded value you choose might clash with the one of
-     * another plugin! *
+     * If multiple plugins override a field, the one with the highest `rank` will win. If
+     * you want to specify an explicit value for `rank`, make sure to offer a way for final
+     * users to customize it inside the plugin's settings form, otherwise the hardcoded
+     * value you choose might clash with the one of another plugin! *
      */
     rank?: number;
     /** The initial height to set for the iframe that will render the field extension */
@@ -202,22 +179,18 @@ export declare type EditorOverride = {
 };
 /** A field addon extension forced on a field */
 export declare type AddonOverride = {
-    /**
-     * ID of field extension. Will be the first argument for the
-     * `renderFieldExtension` function
-     */
+    /** ID of field extension. Will be the first argument for the `renderFieldExtension` function */
     id: string;
     /**
-     * An arbitrary configuration object that will be passed as the `parameters`
-     * property of the second argument of the `renderFieldExtension` function
+     * An arbitrary configuration object that will be passed as the `parameters` property of
+     * the second argument of the `renderFieldExtension` function
      */
     parameters?: Record<string, unknown>;
     /**
-     * If multiple addons are present for a field, they will be sorted by
-     * ascending `rank`. If you want to specify an explicit value for `rank`, make
-     * sure to offer a way for final users to customize it inside the plugin's
-     * settings form, otherwise the hardcoded value you choose might clash with
-     * the one of another plugin! *
+     * If multiple addons are present for a field, they will be sorted by ascending `rank`.
+     * If you want to specify an explicit value for `rank`, make sure to offer a way for
+     * final users to customize it inside the plugin's settings form, otherwise the
+     * hardcoded value you choose might clash with the one of another plugin! *
      */
     rank?: number;
     /** The initial height to set for the iframe that will render the field extension */
@@ -269,8 +242,8 @@ export declare type Modal = {
     /** Width of the modal. Can be a number, or one of the predefined sizes */
     width?: 's' | 'm' | 'l' | 'xl' | 'fullWidth' | number;
     /**
-     * An arbitrary configuration object that will be passed as the `parameters`
-     * property of the second argument of the `renderModal` function
+     * An arbitrary configuration object that will be passed as the `parameters` property of
+     * the second argument of the `renderModal` function
      */
     parameters?: Record<string, unknown>;
     /** The initial height to set for the iframe that will render the modal content */
@@ -286,17 +259,14 @@ export declare type Toast<CtaValue = unknown> = {
     cta?: {
         /** Label for the button */
         label: string;
-        /**
-         * The value to be returned by the `customToast` promise if the button is
-         * clicked by the user
-         */
+        /** The value to be returned by the `customToast` promise if the button is clicked by the user */
         value: CtaValue;
     };
     /** Whether the toast is to be automatically closed if the user changes page */
     dismissOnPageChange?: boolean;
     /**
-     * Whether the toast is to be automatically closed after some time (`true`
-     * will use the default DatoCMS time interval)
+     * Whether the toast is to be automatically closed after some time (`true` will use the
+     * default DatoCMS time interval)
      */
     dismissAfterTimeout?: boolean | number;
 };
@@ -304,10 +274,7 @@ export declare type Toast<CtaValue = unknown> = {
 export declare type ConfirmChoice = {
     /** The label to be shown for the choice */
     label: string;
-    /**
-     * The value to be returned by the `openConfirm` promise if the button is
-     * clicked by the user
-     */
+    /** The value to be returned by the `openConfirm` promise if the button is clicked by the user */
     value: unknown;
     /** The intent of the button. Will present the button in a different color accent. */
     intent?: 'positive' | 'negative';
@@ -332,23 +299,20 @@ export declare type CommonProperties = {
     /** All the models of the current DatoCMS project, indexed by ID */
     itemTypes: Partial<Record<string, ModelBlock>>;
     /**
-     * The current DatoCMS user. It can either be the owner or one of the
-     * collaborators (regular or SSO).
+     * The current DatoCMS user. It can either be the owner or one of the collaborators
+     * (regular or SSO).
      */
     currentUser: User | SsoUser | Account;
     /** The role for the current DatoCMS user */
     currentRole: Role;
     /**
-     * The access token to perform API calls on behalf of the current user. Only
-     * available if `currentAccessToken` permission is granted
+     * The access token to perform API calls on behalf of the current user. Only available
+     * if `currentAccessToken` permission is granted
      */
     currentAccessToken: string | undefined;
     /** The current plugin */
     plugin: Plugin;
-    /**
-     * UI preferences of the current user (right now, only the preferred locale is
-     * available)
-     */
+    /** UI preferences of the current user (right now, only the preferred locale is available) */
     ui: {
         /** Preferred locale */
         locale: string;
@@ -365,25 +329,24 @@ export declare type InitPropertiesAndMethods = InitMethods & InitProperties;
 /** Additional properties available in all `renderXXX` hooks */
 export declare type RenderAdditionalProperties = {
     /**
-     * All the fields currently loaded for the current DatoCMS project, indexed by
-     * ID. It will always contain the current model fields and all the fields of
-     * the blocks it might contain via Modular Content/Structured Text fields. If
-     * some fields you need are not present, use the `loadItemTypeFields` function
-     * to load them.
+     * All the fields currently loaded for the current DatoCMS project, indexed by ID. It
+     * will always contain the current model fields and all the fields of the blocks it
+     * might contain via Modular Content/Structured Text fields. If some fields you need are
+     * not present, use the `loadItemTypeFields` function to load them.
      */
     fields: Partial<Record<string, Field>>;
     /** An object containing the theme colors for the current DatoCMS project */
     theme: Theme;
     /**
-     * All the regular users currently loaded for the current DatoCMS project,
-     * indexed by ID. It will always contain the current user. If some users you
-     * need are not present, use the `loadUsers` function to load them.
+     * All the regular users currently loaded for the current DatoCMS project, indexed by
+     * ID. It will always contain the current user. If some users you need are not present,
+     * use the `loadUsers` function to load them.
      */
     users: Partial<Record<string, User>>;
     /**
-     * All the SSO users currently loaded for the current DatoCMS project, indexed
-     * by ID. It will always contain the current user. If some users you need are
-     * not present, use the `loadSsoUsers` function to load them.
+     * All the SSO users currently loaded for the current DatoCMS project, indexed by ID. It
+     * will always contain the current user. If some users you need are not present, use the
+     * `loadSsoUsers` function to load them.
      */
     ssoUsers: Partial<Record<string, SsoUser>>;
     /** The project owner */
@@ -397,7 +360,7 @@ export declare type FieldAppearanceChange = {
 } | {
     operation: 'updateEditor';
     newFieldExtensionId?: string;
-    newFieldExtensionParameters?: Record<string, unknown>;
+    newParameters?: Record<string, unknown>;
 } | {
     operation: 'setEditor';
     fieldExtensionId: string;
@@ -417,120 +380,146 @@ export declare type FieldAppearanceChange = {
     parameters: Record<string, unknown>;
 };
 /**
- * These methods can be used to update both plugin parameters and manual field
- * extensions configuration.
+ * These methods can be used to update both plugin parameters and manual field extensions
+ * configuration.
  */
 export declare type UpdateParametersMethods = {
     /**
      * Updates the plugin parameters.
      *
-     * Always check `ctx.currentRole.meta.final_permissions.can_edit_schema`
-     * before calling this, as the user might not have the permission to perform
-     * the operation.
+     * Always check `ctx.currentRole.meta.final_permissions.can_edit_schema` before calling
+     * this, as the user might not have the permission to perform the operation.
      *
      * @example
-     *   ctx.updatePluginParameters({ debugMode: true });
+     *   await ctx.updatePluginParameters({ debugMode: true });
+     *   await ctx.notice('Plugin parameters successfully updated!');
      */
     updatePluginParameters: (params: Record<string, unknown>) => Promise<void>;
     /**
-     * Performs changes in the appearance of a field. You can install/remove a
-     * manual field extension, or tweak their parameters. If multiple changes are
-     * passed, they will be applied sequencially.
+     * Performs changes in the appearance of a field. You can install/remove a manual field
+     * extension, or tweak their parameters. If multiple changes are passed, they will be
+     * applied sequencially.
      *
-     * Always check `ctx.currentRole.meta.final_permissions.can_edit_schema`
-     * before calling this, as the user might not have the permission to perform
-     * the operation.
+     * Always check `ctx.currentRole.meta.final_permissions.can_edit_schema` before calling
+     * this, as the user might not have the permission to perform the operation.
      *
      * @example
-     *   const fieldId = 234;
-     *   ctx.updateFieldAppearance(234, [
-     *     {
-     *       operation: 'updateEditor',
-     *       newFieldExtensionParameters: { foo: 'bar' },
-     *     },
-     *     {
-     *       operation: 'updateAddon',
-     *       index: 2,
-     *       newFieldExtensionParameters: { bar: 'qux' },
-     *     },
-     *   ]);
+     *   const fields = await ctx.loadFieldsUsingPlugin();
+     *
+     *   if (fields.length === 0) {
+     *     ctx.alert('No field is using this plugin as a manual extension!');
+     *     return;
+     *   }
+     *
+     *   for (const field of fields) {
+     *     const { appearance } = field.attributes;
+     *     const operations = [];
+     *
+     *     if (appearance.editor === ctx.plugin.id) {
+     *       operations.push({
+     *         operation: 'updateEditor',
+     *         newParameters: {
+     *           ...appearance.parameters,
+     *           foo: 'bar',
+     *         },
+     *       });
+     *     }
+     *
+     *     appearance.addons.forEach((addon, i) => {
+     *       if (addon.id !== ctx.plugin.id) {
+     *         return;
+     *       }
+     *
+     *       operations.push({
+     *         operation: 'updateAddon',
+     *         index: i,
+     *         newParameters: { ...addon.parameters, foo: 'bar' },
+     *       });
+     *     });
+     *
+     *     await ctx.updateFieldAppearance(field.id, operations);
+     *     ctx.notice(`Successfully edited field ${field.attributes.api_key}`);
+     *   }
      */
     updateFieldAppearance: (fieldId: string, changes: FieldAppearanceChange[]) => Promise<void>;
 };
-/**
- * These methods can be used to asyncronously load additional information your
- * plugin needs to work
- */
+/** These methods can be used to asyncronously load additional information your plugin needs to work */
 export declare type LoadDataMethods = {
     /**
-     * Loads all the fields for a specific model (or block). Fields will be
-     * returned and will also be available in the the `fields` property.
+     * Loads all the fields for a specific model (or block). Fields will be returned and
+     * will also be available in the the `fields` property.
      *
      * @example
-     *   const fields = await sdk.loadItemTypeFields('810907');
-     *   sdk.notice(
-     *     `Success! ${fields
-     *       .map((field) => field.attributes.api_key)
-     *       .join(', ')}`,
+     *   const itemTypeId = prompt('Please insert a model ID:');
+     *
+     *   const fields = await ctx.loadItemTypeFields(itemTypeId);
+     *
+     *   ctx.notice(
+     *     `Success! ${fields.map((field) => field.attributes.api_key).join(', ')}`,
      *   );
      */
     loadItemTypeFields: (itemTypeId: string) => Promise<Field[]>;
     /**
-     * Loads all the fields in the project that are currently using the plugin for
-     * one of its manual field extensions.
+     * Loads all the fields in the project that are currently using the plugin for one of
+     * its manual field extensions.
      *
      * @example
-     *   const fields = await sdk.loadFieldsUsingPlugin();
-     *   sdk.notice(
-     *     `Success! ${fields
-     *       .map((field) => field.attributes.api_key)
-     *       .join(', ')}`,
+     *   const fields = await ctx.loadFieldsUsingPlugin();
+     *
+     *   ctx.notice(
+     *     `Success! ${fields.map((field) => field.attributes.api_key).join(', ')}`,
      *   );
      */
     loadFieldsUsingPlugin: () => Promise<Field[]>;
     /**
-     * Loads all regular users. Users will be returned and will also be available
-     * in the the `users` property.
+     * Loads all regular users. Users will be returned and will also be available in the the
+     * `users` property.
      *
      * @example
-     *   const users = await sdk.loadUsers();
-     *   sdk.notice(`Success! ${users.map((user) => i.id).join(', ')}`);
+     *   const users = await ctx.loadUsers();
+     *
+     *   ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);
      */
     loadUsers: () => Promise<User[]>;
     /**
-     * Loads all SSO users. Users will be returned and will also be available in
-     * the the `ssoUsers` property.
+     * Loads all SSO users. Users will be returned and will also be available in the the
+     * `ssoUsers` property.
      *
      * @example
-     *   const users = await sdk.loadSsoUsers();
-     *   sdk.notice(`Success! ${users.map((user) => i.id).join(', ')}`);
+     *   const users = await ctx.loadSsoUsers();
+     *
+     *   ctx.notice(`Success! ${users.map((user) => user.id).join(', ')}`);
      */
     loadSsoUsers: () => Promise<SsoUser[]>;
 };
 /** These methods let you open the standard DatoCMS dialogs needed to interact with records */
 export declare type ItemDialogMethods = {
     /**
-     * Opens a dialog for creating a new record. It returns a promise resolved
-     * with the newly created record or `null` if the user closes the dialog
-     * without creating anything.
+     * Opens a dialog for creating a new record. It returns a promise resolved with the
+     * newly created record or `null` if the user closes the dialog without creating anything.
      *
      * @example
-     *   const item = await sdk.createNewItem('810907');
+     *   const itemTypeId = prompt('Please insert a model ID:');
+     *
+     *   const item = await ctx.createNewItem(itemTypeId);
+     *
      *   if (item) {
-     *     sdk.notice(`Success! ${item.id}`);
+     *     ctx.notice(`Success! ${item.id}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     createNewItem: (itemTypeId: string) => Promise<Item | null>;
     /**
-     * Opens a dialog for selecting one (or multiple) record(s) from a list of
-     * existing records of type `itemTypeId`. It returns a promise resolved with
-     * the selected record(s), or `null` if the user closes the dialog without
-     * choosing any record.
+     * Opens a dialog for selecting one (or multiple) record(s) from a list of existing
+     * records of type `itemTypeId`. It returns a promise resolved with the selected
+     * record(s), or `null` if the user closes the dialog without choosing any record.
      *
      * @example
-     *   const items = await ctx.selectItem('810907', { multiple: true });
+     *   const itemTypeId = prompt('Please insert a model ID:');
+     *
+     *   const items = await ctx.selectItem(itemTypeId, { multiple: true });
+     *
      *   if (items) {
      *     ctx.notice(`Success! ${items.map((i) => i.id).join(', ')}`);
      *   } else {
@@ -546,17 +535,18 @@ export declare type ItemDialogMethods = {
         }): Promise<Item | null>;
     };
     /**
-     * Opens a dialog for editing an existing record. It returns a promise
-     * resolved with the edited record, or `null` if the user closes the dialog
-     * without persisting any change.
+     * Opens a dialog for editing an existing record. It returns a promise resolved with the
+     * edited record, or `null` if the user closes the dialog without persisting any change.
      *
      * @example
-     *   const item = await sdk.editItem('50479504');
+     *   const itemId = prompt('Please insert a record ID:');
+     *
+     *   const item = await ctx.editItem(itemId);
      *
      *   if (item) {
-     *     sdk.notice(`Success! ${item.id}`);
+     *     ctx.notice(`Success! ${item.id}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     editItem: (itemId: string) => Promise<Item | null>;
@@ -567,25 +557,29 @@ export declare type ToastMethods = {
      * Triggers an "error" toast displaying the selected message
      *
      * @example
-     *   sdk.alert('Alert!');
+     *   const message = prompt('Please insert a message:', 'This is an alert message!');
+     *
+     *   await ctx.alert(message);
      */
-    alert: (message: string) => void;
+    alert: (message: string) => Promise<void>;
     /**
      * Triggers a "success" toast displaying the selected message
      *
      * @example
-     *   sdk.notice('Notice!');
+     *   const message = prompt('Please insert a message:', 'This is a notice message!');
+     *
+     *   await ctx.notice(message);
      */
-    notice: (message: string) => void;
+    notice: (message: string) => Promise<void>;
     /**
      * Triggers a custom toast displaying the selected message (and optionally a CTA)
      *
      * @example
-     *   const result = await sdk.customToast({
+     *   const result = await ctx.customToast({
      *     type: 'warning',
      *     message: 'Just a sample warning notification!',
      *     dismissOnPageChange: true,
-     *     dismissAfterTimeout: 22000,
+     *     dismissAfterTimeout: 5000,
      *     cta: {
      *       label: 'Execute call-to-action',
      *       value: 'cta',
@@ -593,28 +587,25 @@ export declare type ToastMethods = {
      *   });
      *
      *   if (result === 'cta') {
-     *     sdk.notice(`Clicked CTA!`);
+     *     ctx.notice(`Clicked CTA!`);
      *   }
      */
     customToast: <CtaValue = unknown>(toast: Toast<CtaValue>) => Promise<CtaValue | null>;
 };
-/**
- * These methods let you open the standard DatoCMS dialogs needed to interact
- * with Media Area assets
- */
+/** These methods let you open the standard DatoCMS dialogs needed to interact with Media Area assets */
 export declare type UploadDialogMethods = {
     /**
-     * Opens a dialog for selecting one (or multiple) existing asset(s). It
-     * returns a promise resolved with the selected asset(s), or `null` if the
-     * user closes the dialog without selecting any upload.
+     * Opens a dialog for selecting one (or multiple) existing asset(s). It returns a
+     * promise resolved with the selected asset(s), or `null` if the user closes the dialog
+     * without selecting any upload.
      *
      * @example
-     *   const item = await sdk.selectUpload({ multiple: false });
+     *   const item = await ctx.selectUpload({ multiple: false });
      *
      *   if (item) {
-     *     sdk.notice(`Success! ${item.id}`);
+     *     ctx.notice(`Success! ${item.id}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     selectUpload: {
@@ -630,29 +621,33 @@ export declare type UploadDialogMethods = {
      *
      * - The updated asset, if the user persists some changes to the asset itself
      * - `null`, if the user closes the dialog without persisting any change
-     * - An asset structure with an additional `deleted` property set to true, if
-     *   the user deletes the asset
+     * - An asset structure with an additional `deleted` property set to true, if the user
+     *   deletes the asset
      *
      * @example
-     *   const item = await sdk.editUpload('21717537');
+     *   const uploadId = prompt('Please insert an asset ID:');
+     *
+     *   const item = await ctx.editUpload(uploadId);
      *
      *   if (item) {
-     *     sdk.notice(`Success! ${item.id}`);
+     *     ctx.notice(`Success! ${item.id}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     editUpload: (uploadId: string) => Promise<(Upload & {
         deleted?: true;
     }) | null>;
     /**
-     * Opens a dialog for editing a "single asset" field structure. It returns a
-     * promise resolved with the updated structure, or `null` if the user closes
-     * the dialog without persisting any change.
+     * Opens a dialog for editing a "single asset" field structure. It returns a promise
+     * resolved with the updated structure, or `null` if the user closes the dialog without
+     * persisting any change.
      *
      * @example
-     *   const result = await sdk.editUploadMetadata({
-     *     upload_id: '21717537',
+     *   const uploadId = prompt('Please insert an asset ID:');
+     *
+     *   const result = await ctx.editUploadMetadata({
+     *     upload_id: uploadId,
      *     alt: null,
      *     title: null,
      *     custom_data: {},
@@ -660,9 +655,9 @@ export declare type UploadDialogMethods = {
      *   });
      *
      *   if (result) {
-     *     sdk.notice(`Success! ${JSON.stringify(result)}`);
+     *     ctx.notice(`Success! ${JSON.stringify(result)}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     editUploadMetadata: (
@@ -674,29 +669,30 @@ export declare type UploadDialogMethods = {
 /** These methods can be used to open custom dialogs/confirmation panels */
 export declare type CustomDialogMethods = {
     /**
-     * Opens a custom modal. Returns a promise resolved with what the modal itself
-     * returns calling the `resolve()` function
+     * Opens a custom modal. Returns a promise resolved with what the modal itself returns
+     * calling the `resolve()` function
      *
      * @example
-     *   const result = await sdk.openModal({
+     *   const result = await ctx.openModal({
      *     id: 'regular',
      *     title: 'Custom title!',
      *     width: 'l',
      *     parameters: { foo: 'bar' },
      *   });
+     *
      *   if (result) {
-     *     sdk.notice(`Success! ${JSON.stringify(result)}`);
+     *     ctx.notice(`Success! ${JSON.stringify(result)}`);
      *   } else {
-     *     sdk.alert('Closed!');
+     *     ctx.alert('Closed!');
      *   }
      */
     openModal: (modal: Modal) => Promise<unknown>;
     /**
-     * Opens a UI-consistent confirmation dialog. Returns a promise resolved with
-     * the value of the choice made by the user
+     * Opens a UI-consistent confirmation dialog. Returns a promise resolved with the value
+     * of the choice made by the user
      *
      * @example
-     *   const result = await sdk.openConfirm({
+     *   const result = await ctx.openConfirm({
      *     title: 'Custom title',
      *     content:
      *       'Lorem Ipsum is simply dummy text of the printing and typesetting industry',
@@ -717,10 +713,11 @@ export declare type CustomDialogMethods = {
      *       value: false,
      *     },
      *   });
+     *
      *   if (result) {
-     *     sdk.notice(`Success! ${result}`);
+     *     ctx.notice(`Success! ${result}`);
      *   } else {
-     *     sdk.alert('Cancelled!');
+     *     ctx.alert('Cancelled!');
      *   }
      */
     openConfirm: (options: ConfirmOptions) => Promise<unknown>;
@@ -731,19 +728,19 @@ export declare type NavigateMethods = {
      * Moves the user to another URL internal to the backend
      *
      * @example
-     *   sdk.navigateTo('/');
+     *   await ctx.navigateTo('/');
      */
-    navigateTo: (path: string) => void;
+    navigateTo: (path: string) => Promise<void>;
 };
 /** These methods can be used to set various properties of the containing iframe */
 export declare type IframeMethods = {
     /** Sets the height for the iframe */
-    setHeight: (number: number) => void;
+    setHeight: (number: number) => Promise<void>;
 };
 export declare type RenderMethods = LoadDataMethods & UpdateParametersMethods & ToastMethods & CustomDialogMethods & NavigateMethods;
 /**
- * These information describe the current state of the form that's being shown
- * to the end-user to edit a record
+ * These information describe the current state of the form that's being shown to the
+ * end-user to edit a record
  */
 export declare type ItemFormAdditionalProperties = {
     /** The currently active locale for the record */
@@ -763,44 +760,64 @@ export declare type ItemFormAdditionalProperties = {
 };
 export declare type ItemFormProperties = RenderProperties & ItemFormAdditionalProperties;
 /**
- * These methods can be used to interact with the form that's being shown to the
- * end-user to edit a record
+ * These methods can be used to interact with the form that's being shown to the end-user
+ * to edit a record
  */
 export declare type ItemFormAdditionalMethods = {
     /**
      * Hides/shows a specific field in the form
      *
      * @example
-     *   sdk.toggleField(sdk.fieldPath, true);
+     *   const fieldPath = prompt(
+     *     'Please insert the path of a field in the form',
+     *     ctx.fieldPath,
+     *   );
+     *
+     *   await ctx.toggleField(fieldPath, true);
      */
-    toggleField: (path: string, show: boolean) => void;
+    toggleField: (path: string, show: boolean) => Promise<void>;
     /**
      * Disables/re-enables a specific field in the form
      *
      * @example
-     *   sdk.disableField(sdk.fieldPath, true);
+     *   const fieldPath = prompt(
+     *     'Please insert the path of a field in the form',
+     *     ctx.fieldPath,
+     *   );
+     *
+     *   await ctx.disableField(fieldPath, true);
      */
-    disableField: (path: string, disable: boolean) => void;
+    disableField: (path: string, disable: boolean) => Promise<void>;
     /**
-     * Smoothly navigates to a specific field in the form. If the field is
-     * localized it will switch language tab and then navigate to the chosen field.
+     * Smoothly navigates to a specific field in the form. If the field is localized it will
+     * switch language tab and then navigate to the chosen field.
      *
      * @example
-     *   sdk.scrollToField(sdk.fieldPath);
+     *   const fieldPath = prompt(
+     *     'Please insert the path of a field in the form',
+     *     ctx.fieldPath,
+     *   );
+     *
+     *   await ctx.scrollToField(fieldPath);
      */
-    scrollToField: (path: string, locale?: string) => void;
+    scrollToField: (path: string, locale?: string) => Promise<void>;
     /**
      * Changes a specific path of the `formValues` object
      *
      * @example
-     *   sdk.setFieldValue(sdk.fieldPath, 'new value');
+     *   const fieldPath = prompt(
+     *     'Please insert the path of a field in the form',
+     *     ctx.fieldPath,
+     *   );
+     *
+     *   await ctx.setFieldValue(fieldPath, 'new value');
      */
-    setFieldValue: (path: string, value: unknown) => void;
+    setFieldValue: (path: string, value: unknown) => Promise<void>;
     /**
      * Triggers a submit form for current record
      *
      * @example
-     *   await sdk.saveCurrentItem();
+     *   await ctx.saveCurrentItem();
      */
     saveCurrentItem: () => Promise<void>;
 };
@@ -810,10 +827,7 @@ export declare type RenderSidebarPanelAdditionalProperties = {
     mode: 'renderItemFormSidebarPanel';
     /** The ID of the sidebar panel that needs to be rendered */
     sidebarPaneId: string;
-    /**
-     * The arbitrary `parameters` of the panel declared in the
-     * `itemFormSidebarPanels` function
-     */
+    /** The arbitrary `parameters` of the panel declared in the `itemFormSidebarPanels` function */
     parameters: Record<string, unknown>;
 };
 export declare type RenderSidebarPanelProperties = ItemFormProperties & RenderSidebarPanelAdditionalProperties;
@@ -822,10 +836,7 @@ export declare type RenderSidebarPanelAdditionalMethods = {
 };
 export declare type RenderSidebarPanelMethods = ItemFormMethods & RenderSidebarPanelAdditionalMethods;
 export declare type RenderSidebarPanePropertiesAndMethods = RenderSidebarPanelMethods & RenderSidebarPanelProperties;
-/**
- * Information regarding the state of a specific field where you need to render
- * the field extension
- */
+/** Information regarding the state of a specific field where you need to render the field extension */
 export declare type RenderFieldExtensionAdditionalProperties = {
     mode: 'renderFieldExtension';
     /** The ID of the field extension that needs to be rendered */
@@ -841,8 +852,8 @@ export declare type RenderFieldExtensionAdditionalProperties = {
     /** The field where the field extension is installed to */
     field: Field;
     /**
-     * If the field extension is installed in a field of a block, returns the top
-     * level Modular Content/Structured Text field containing the block itself
+     * If the field extension is installed in a field of a block, returns the top level
+     * Modular Content/Structured Text field containing the block itself
      */
     parentField: Field | undefined;
 };
@@ -865,10 +876,18 @@ export declare type RenderModalProperties = RenderProperties & RenderModalAdditi
 export declare type RenderModalAdditionalMethods = {
     getSettings: () => Promise<RenderModalProperties>;
     /**
-     * A function to be called by the plugin to close the modal. The `openModal`
-     * call will be resolved with the passed return value
+     * A function to be called by the plugin to close the modal. The `openModal` call will
+     * be resolved with the passed return value
+     *
+     * @example
+     *   const returnValue = prompt(
+     *     'Please specify the value to return to the caller:',
+     *     'success',
+     *   );
+     *
+     *   await ctx.resolve(returnValue);
      */
-    resolve: (returnValue: unknown) => void;
+    resolve: (returnValue: unknown) => Promise<void>;
 };
 export declare type RenderModalMethods = RenderMethods & IframeMethods & RenderModalAdditionalMethods;
 export declare type RenderModalPropertiesAndMethods = RenderModalMethods & RenderModalProperties;
@@ -885,8 +904,8 @@ export declare type RenderPageAdditionalMethods = {
 export declare type RenderPageMethods = RenderMethods & RenderPageAdditionalMethods;
 export declare type RenderPagePropertiesAndMethods = RenderPageMethods & RenderPageProperties;
 /**
- * Information regarding the specific form that you need to render to let the
- * end-user edit the configuration object of a field extension
+ * Information regarding the specific form that you need to render to let the end-user
+ * edit the configuration object of a field extension
  */
 export declare type RenderManualFieldExtensionConfigScreenAdditionalProperties = {
     mode: 'renderManualFieldExtensionConfigScreen';
@@ -898,23 +917,20 @@ export declare type RenderManualFieldExtensionConfigScreenAdditionalProperties =
      */
     parameters: Record<string, unknown>;
     /**
-     * The current validation errors for the parameters (you can set them
-     * implementing the `validateManualFieldExtensionParameters` function)
+     * The current validation errors for the parameters (you can set them implementing the
+     * `validateManualFieldExtensionParameters` function)
      */
     errors: Record<string, unknown>;
 };
 export declare type RenderManualFieldExtensionConfigScreenProperties = RenderProperties & RenderManualFieldExtensionConfigScreenAdditionalProperties;
-/**
- * These methods can be used to update the configuration object of a specific
- * field extension
- */
+/** These methods can be used to update the configuration object of a specific field extension */
 export declare type RenderManualFieldExtensionConfigScreenAdditionalMethods = {
     getSettings: () => Promise<RenderManualFieldExtensionConfigScreenProperties>;
     /**
      * Sets a new value for the parameters
      *
      * @example
-     *   ctx.setParameters({ color: '#ff0000' });
+     *   await ctx.setParameters({ color: '#ff0000' });
      */
     setParameters: (params: Record<string, unknown>) => Promise<void>;
 };