datocms-plugin-sdk 0.3.1 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # `datocms-plugin-sdk`
 
-A set of Typescript types and helpers to work with DatoCMS Structured Text fields.
+Typescript SDK to build DatoCMS plugins. You can read all about the SDK in [our documentation](https://www.datocms.com/docs/plugin-sdk).
 
 ## Installation
 

package/dist/esm/types.d.ts

@@ -442,8 +442,9 @@ export declare type UpdateParametersMethods = {
      * the operation.
      *
      * @example
-     *   const fieldId = 234;
-     *   ctx.updateFieldAppearance(234, [
+     *   const fieldId = prompt('Please insert a field ID:');
+     *
+     *   ctx.updateFieldAppearance(fieldId, [
      *     {
      *       operation: 'updateEditor',
      *       newFieldExtensionParameters: { foo: 'bar' },
@@ -467,8 +468,11 @@ export declare type LoadDataMethods = {
      * returned and will also be available in the the `fields` property.
      *
      * @example
-     *   const fields = await sdk.loadItemTypeFields('810907');
-     *   sdk.notice(
+     *   const fieldId = prompt('Please insert a field ID:');
+     *
+     *   const fields = await ctx.loadItemTypeFields(fieldId);
+     *
+     *   ctx.notice(
      *     `Success! ${fields
      *       .map((field) => field.attributes.api_key)
      *       .join(', ')}`,
@@ -480,8 +484,9 @@ export declare type LoadDataMethods = {
      * one of its manual field extensions.
      *
      * @example
-     *   const fields = await sdk.loadFieldsUsingPlugin();
-     *   sdk.notice(
+     *   const fields = await ctx.loadFieldsUsingPlugin();
+     *
+     *   ctx.notice(
      *     `Success! ${fields
      *       .map((field) => field.attributes.api_key)
      *       .join(', ')}`,
@@ -493,8 +498,9 @@ export declare type LoadDataMethods = {
      * 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) => i.id).join(', ')}`);
      */
     loadUsers: () => Promise<User[]>;
     /**
@@ -502,8 +508,9 @@ export declare type LoadDataMethods = {
      * 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) => i.id).join(', ')}`);
      */
     loadSsoUsers: () => Promise<SsoUser[]>;
 };
@@ -515,11 +522,14 @@ export declare type ItemDialogMethods = {
      * 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>;
@@ -530,7 +540,10 @@ export declare type ItemDialogMethods = {
      * 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 {
@@ -551,12 +564,14 @@ export declare type ItemDialogMethods = {
      * 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 +582,35 @@ 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!',
+     *   );
+     *
+     *   ctx.alert(message);
      */
     alert: (message: string) => 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!',
+     *   );
+     *
+     *   ctx.notice(message);
      */
     notice: (message: string) => 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,7 +618,7 @@ export declare type ToastMethods = {
      *   });
      *
      *   if (result === 'cta') {
-     *     sdk.notice(`Clicked CTA!`);
+     *     ctx.notice(`Clicked CTA!`);
      *   }
      */
     customToast: <CtaValue = unknown>(toast: Toast<CtaValue>) => Promise<CtaValue | null>;
@@ -609,12 +634,12 @@ export declare type UploadDialogMethods = {
      * 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: {
@@ -634,12 +659,14 @@ export declare type UploadDialogMethods = {
      *   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 & {
@@ -651,8 +678,10 @@ export declare type UploadDialogMethods = {
      * 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 +689,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: (
@@ -678,16 +707,17 @@ export declare type CustomDialogMethods = {
      * 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>;
@@ -696,7 +726,7 @@ export declare type CustomDialogMethods = {
      * 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 +747,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,7 +762,7 @@ export declare type NavigateMethods = {
      * Moves the user to another URL internal to the backend
      *
      * @example
-     *   sdk.navigateTo('/');
+     *   ctx.navigateTo('/');
      */
     navigateTo: (path: string) => void;
 };
@@ -771,14 +802,23 @@ 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,
+     *   );
+     *
+     *   ctx.toggleField(fieldPath, true);
      */
     toggleField: (path: string, show: boolean) => 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,
+     *   );
+     *   ctx.disableField(fieldPath, true);
      */
     disableField: (path: string, disable: boolean) => void;
     /**
@@ -786,21 +826,29 @@ export declare type ItemFormAdditionalMethods = {
      * 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,
+     *   );
+     *   ctx.scrollToField(fieldPath);
      */
     scrollToField: (path: string, locale?: string) => 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,
+     *   );
+     *   ctx.setFieldValue(fieldPath, 'new value');
      */
     setFieldValue: (path: string, value: unknown) => void;
     /**
      * Triggers a submit form for current record
      *
      * @example
-     *   await sdk.saveCurrentItem();
+     *   await ctx.saveCurrentItem();
      */
     saveCurrentItem: () => Promise<void>;
 };
@@ -867,6 +915,14 @@ export declare type RenderModalAdditionalMethods = {
     /**
      * 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',
+     *   );
+     *
+     *   ctx.resolve(returnValue);
      */
     resolve: (returnValue: unknown) => void;
 };

package/dist/types/types.d.ts

@@ -442,8 +442,9 @@ export declare type UpdateParametersMethods = {
      * the operation.
      *
      * @example
-     *   const fieldId = 234;
-     *   ctx.updateFieldAppearance(234, [
+     *   const fieldId = prompt('Please insert a field ID:');
+     *
+     *   ctx.updateFieldAppearance(fieldId, [
      *     {
      *       operation: 'updateEditor',
      *       newFieldExtensionParameters: { foo: 'bar' },
@@ -467,8 +468,11 @@ export declare type LoadDataMethods = {
      * returned and will also be available in the the `fields` property.
      *
      * @example
-     *   const fields = await sdk.loadItemTypeFields('810907');
-     *   sdk.notice(
+     *   const fieldId = prompt('Please insert a field ID:');
+     *
+     *   const fields = await ctx.loadItemTypeFields(fieldId);
+     *
+     *   ctx.notice(
      *     `Success! ${fields
      *       .map((field) => field.attributes.api_key)
      *       .join(', ')}`,
@@ -480,8 +484,9 @@ export declare type LoadDataMethods = {
      * one of its manual field extensions.
      *
      * @example
-     *   const fields = await sdk.loadFieldsUsingPlugin();
-     *   sdk.notice(
+     *   const fields = await ctx.loadFieldsUsingPlugin();
+     *
+     *   ctx.notice(
      *     `Success! ${fields
      *       .map((field) => field.attributes.api_key)
      *       .join(', ')}`,
@@ -493,8 +498,9 @@ export declare type LoadDataMethods = {
      * 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) => i.id).join(', ')}`);
      */
     loadUsers: () => Promise<User[]>;
     /**
@@ -502,8 +508,9 @@ export declare type LoadDataMethods = {
      * 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) => i.id).join(', ')}`);
      */
     loadSsoUsers: () => Promise<SsoUser[]>;
 };
@@ -515,11 +522,14 @@ export declare type ItemDialogMethods = {
      * 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>;
@@ -530,7 +540,10 @@ export declare type ItemDialogMethods = {
      * 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 {
@@ -551,12 +564,14 @@ export declare type ItemDialogMethods = {
      * 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 +582,35 @@ 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!',
+     *   );
+     *
+     *   ctx.alert(message);
      */
     alert: (message: string) => 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!',
+     *   );
+     *
+     *   ctx.notice(message);
      */
     notice: (message: string) => 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,7 +618,7 @@ export declare type ToastMethods = {
      *   });
      *
      *   if (result === 'cta') {
-     *     sdk.notice(`Clicked CTA!`);
+     *     ctx.notice(`Clicked CTA!`);
      *   }
      */
     customToast: <CtaValue = unknown>(toast: Toast<CtaValue>) => Promise<CtaValue | null>;
@@ -609,12 +634,12 @@ export declare type UploadDialogMethods = {
      * 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: {
@@ -634,12 +659,14 @@ export declare type UploadDialogMethods = {
      *   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 & {
@@ -651,8 +678,10 @@ export declare type UploadDialogMethods = {
      * 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 +689,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: (
@@ -678,16 +707,17 @@ export declare type CustomDialogMethods = {
      * 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>;
@@ -696,7 +726,7 @@ export declare type CustomDialogMethods = {
      * 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 +747,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,7 +762,7 @@ export declare type NavigateMethods = {
      * Moves the user to another URL internal to the backend
      *
      * @example
-     *   sdk.navigateTo('/');
+     *   ctx.navigateTo('/');
      */
     navigateTo: (path: string) => void;
 };
@@ -771,14 +802,23 @@ 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,
+     *   );
+     *
+     *   ctx.toggleField(fieldPath, true);
      */
     toggleField: (path: string, show: boolean) => 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,
+     *   );
+     *   ctx.disableField(fieldPath, true);
      */
     disableField: (path: string, disable: boolean) => void;
     /**
@@ -786,21 +826,29 @@ export declare type ItemFormAdditionalMethods = {
      * 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,
+     *   );
+     *   ctx.scrollToField(fieldPath);
      */
     scrollToField: (path: string, locale?: string) => 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,
+     *   );
+     *   ctx.setFieldValue(fieldPath, 'new value');
      */
     setFieldValue: (path: string, value: unknown) => void;
     /**
      * Triggers a submit form for current record
      *
      * @example
-     *   await sdk.saveCurrentItem();
+     *   await ctx.saveCurrentItem();
      */
     saveCurrentItem: () => Promise<void>;
 };
@@ -867,6 +915,14 @@ export declare type RenderModalAdditionalMethods = {
     /**
      * 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',
+     *   );
+     *
+     *   ctx.resolve(returnValue);
      */
     resolve: (returnValue: unknown) => void;
 };