Automated Spec Update (#905)

895e08a3fa941888c2c57681c8117a294f8fa4b9

 Change Notes:

common Namespace
- Update comments

files Namespace
- Add UploadArg extends CommitInfo structs
- Add UploadSessionAppendError extends UploadSessionLookupError unions
- Remove CommitInfoWithProperties extends CommitInfo structs
- Remove UploadErrorWithProperties extends UploadError unions

Co-authored-by: DropboxBot <DropboxBot@users.noreply.github.com>
Co-authored-by: Brent Bumann <bbumann@dropbox.com>

Author: DropboxBot

generator/dropbox-api-spec

@@ -434,16 +434,16 @@ routes.filesAlphaGetMetadata = function (arg) {
 };
 
 /**
- * Create a new file with the contents provided in the request. Note that this
- * endpoint is part of the properties API alpha and is slightly different from
- * upload. Do not use this to upload a file larger than 150 MB. Instead, create
- * an upload session with upload_session/start.
+ * Create a new file with the contents provided in the request. Note that the
+ * behavior of this alpha endpoint is unstable and subject to change. Do not use
+ * this to upload a file larger than 150 MB. Instead, create an upload session
+ * with upload_session/start.
  * Route attributes:
  *   scope: files.content.write
  * @function Dropbox#filesAlphaUpload
  * @deprecated
- * @arg {FilesCommitInfoWithProperties} arg - The request parameters.
- * @returns {Promise.<DropboxResponse<FilesFileMetadata>, DropboxResponseError.<FilesUploadErrorWithProperties>>}
+ * @arg {FilesUploadArg} arg - The request parameters.
+ * @returns {Promise.<DropboxResponse<FilesFileMetadata>, DropboxResponseError.<FilesUploadError>>}
  */
 routes.filesAlphaUpload = function (arg) {
   return this.request('files/alpha/upload', arg, 'user', 'content', 'upload', 'files.content.write');
@@ -1314,7 +1314,7 @@ routes.filesUnlockFileBatch = function (arg) {
  * Route attributes:
  *   scope: files.content.write
  * @function Dropbox#filesUpload
- * @arg {FilesCommitInfo} arg - The request parameters.
+ * @arg {FilesUploadArg} arg - The request parameters.
  * @returns {Promise.<DropboxResponse<FilesFileMetadata>, DropboxResponseError.<FilesUploadError>>}
  */
 routes.filesUpload = function (arg) {
@@ -1333,7 +1333,7 @@ routes.filesUpload = function (arg) {
  *   scope: files.content.write
  * @function Dropbox#filesUploadSessionAppendV2
  * @arg {FilesUploadSessionAppendArg} arg - The request parameters.
- * @returns {Promise.<DropboxResponse<void>, DropboxResponseError.<FilesUploadSessionLookupError>>}
+ * @returns {Promise.<DropboxResponse<void>, DropboxResponseError.<FilesUploadSessionAppendError>>}
  */
 routes.filesUploadSessionAppendV2 = function (arg) {
   return this.request('files/upload_session/append_v2', arg, 'user', 'content', 'upload', 'files.content.write');
@@ -1351,7 +1351,7 @@ routes.filesUploadSessionAppendV2 = function (arg) {
  * @function Dropbox#filesUploadSessionAppend
  * @deprecated
  * @arg {FilesUploadSessionCursor} arg - The request parameters.
- * @returns {Promise.<DropboxResponse<void>, DropboxResponseError.<FilesUploadSessionLookupError>>}
+ * @returns {Promise.<DropboxResponse<void>, DropboxResponseError.<FilesUploadSessionAppendError>>}
  */
 routes.filesUploadSessionAppend = function (arg) {
   return this.request('files/upload_session/append', arg, 'user', 'content', 'upload', 'files.content.write');

lib/routes.js

@@ -821,33 +821,6 @@ only present when needed to discriminate between multiple possible subtypes.
 
 /**
  * @typedef {Object} FilesCommitInfo
- * @property {Object} [contents] - The file contents to be uploaded.
- * @property {string} path - Path in the user's Dropbox to save the file.
- * @property {FilesWriteMode} mode - Selects what to do if the file already
- * exists.
- * @property {boolean} autorename - If there's a conflict, as determined by
- * mode, have the Dropbox server try to autorename the file to avoid conflict.
- * @property {Timestamp} [client_modified] - The value to store as the
- * client_modified timestamp. Dropbox automatically records the time at which
- * the file was written to the Dropbox servers. It can also record an additional
- * timestamp, provided by Dropbox desktop clients, mobile clients, and API apps
- * of when the file was actually created or modified.
- * @property {boolean} mute - Normally, users are made aware of any file
- * modifications in their Dropbox account via notifications in the client
- * software. If true, this tells the clients that this modification shouldn't
- * result in a user notification.
- * @property {Array.<FilePropertiesPropertyGroup>} [property_groups] - List of
- * custom properties to add to file.
- * @property {boolean} strict_conflict - Be more strict about how each WriteMode
- * detects conflict. For example, always return a conflict error when mode =
- * WriteMode.update and the given "rev" doesn't match the existing file's "rev",
- * even if the existing file has been deleted. This also forces a conflict even
- * when the target path refers to a file with identical contents.
- */
-
-/**
- * @typedef {Object} FilesCommitInfoWithProperties
- * @property {Object} [contents] - The file contents to be uploaded.
  * @property {string} path - Path in the user's Dropbox to save the file.
  * @property {FilesWriteMode} mode - Selects what to do if the file already
  * exists.
@@ -2291,23 +2264,43 @@ only present when needed to discriminate between multiple possible subtypes.
  */
 
 /**
- * @typedef {Object} FilesUploadError
- * @property {FilesUploadWriteFailed} [path] - Available if .tag is path. Unable
- * to save the uploaded contents to a file.
- * @property {FilePropertiesInvalidPropertyGroupError} [properties_error] -
- * Available if .tag is properties_error. The supplied property group is
- * invalid. The file has uploaded without property groups.
- * @property {('path'|'properties_error'|'payload_too_large'|'other')} .tag - Tag identifying the union variant.
+ * @typedef {Object} FilesUploadArg
+ * @property {Object} [contents] - The file contents to be uploaded.
+ * @property {string} path - Path in the user's Dropbox to save the file.
+ * @property {FilesWriteMode} mode - Selects what to do if the file already
+ * exists.
+ * @property {boolean} autorename - If there's a conflict, as determined by
+ * mode, have the Dropbox server try to autorename the file to avoid conflict.
+ * @property {Timestamp} [client_modified] - The value to store as the
+ * client_modified timestamp. Dropbox automatically records the time at which
+ * the file was written to the Dropbox servers. It can also record an additional
+ * timestamp, provided by Dropbox desktop clients, mobile clients, and API apps
+ * of when the file was actually created or modified.
+ * @property {boolean} mute - Normally, users are made aware of any file
+ * modifications in their Dropbox account via notifications in the client
+ * software. If true, this tells the clients that this modification shouldn't
+ * result in a user notification.
+ * @property {Array.<FilePropertiesPropertyGroup>} [property_groups] - List of
+ * custom properties to add to file.
+ * @property {boolean} strict_conflict - Be more strict about how each WriteMode
+ * detects conflict. For example, always return a conflict error when mode =
+ * WriteMode.update and the given "rev" doesn't match the existing file's "rev",
+ * even if the existing file has been deleted. This also forces a conflict even
+ * when the target path refers to a file with identical contents.
+ * @property {string} [content_hash] - NOT YET SUPPORTED. A hash of the file
+ * content uploaded in this call. If provided and the uploaded content does not
+ * match this hash, an error will be returned. For more information see our
+ * Content hash https://www.dropbox.com/developers/reference/content-hash page.
  */
 
 /**
- * @typedef {Object} FilesUploadErrorWithProperties
+ * @typedef {Object} FilesUploadError
  * @property {FilesUploadWriteFailed} [path] - Available if .tag is path. Unable
  * to save the uploaded contents to a file.
  * @property {FilePropertiesInvalidPropertyGroupError} [properties_error] -
  * Available if .tag is properties_error. The supplied property group is
  * invalid. The file has uploaded without property groups.
- * @property {('path'|'properties_error'|'payload_too_large'|'other')} .tag - Tag identifying the union variant.
+ * @property {('path'|'properties_error'|'payload_too_large'|'content_hash_mismatch'|'other')} .tag - Tag identifying the union variant.
  */
 
 /**
@@ -2318,6 +2311,20 @@ only present when needed to discriminate between multiple possible subtypes.
  * @property {boolean} close - If true, the current session will be closed, at
  * which point you won't be able to call upload_session/append:2 anymore with
  * the current session.
+ * @property {string} [content_hash] - NOT YET SUPPORTED. A hash of the file
+ * content uploaded in this call. If provided and the uploaded content does not
+ * match this hash, an error will be returned. For more information see our
+ * Content hash https://www.dropbox.com/developers/reference/content-hash page.
+ */
+
+/**
+ * @typedef {Object} FilesUploadSessionAppendError
+ * @property {FilesUploadSessionOffsetError} [incorrect_offset] - Available if
+ * .tag is incorrect_offset. The specified offset was incorrect. See the value
+ * for the correct offset. This error may occur when a previous request was
+ * received and processed successfully but the client did not receive the
+ * response, e.g. due to a network error.
+ * @property {('not_found'|'incorrect_offset'|'closed'|'not_closed'|'too_large'|'concurrent_session_invalid_offset'|'concurrent_session_invalid_data_size'|'payload_too_large'|'other'|'content_hash_mismatch')} .tag - Tag identifying the union variant.
  */
 
 /**
@@ -2337,6 +2344,10 @@ only present when needed to discriminate between multiple possible subtypes.
  * and the offset.
  * @property {FilesCommitInfo} commit - Contains the path and other optional
  * modifiers for the commit.
+ * @property {string} [content_hash] - NOT YET SUPPORTED. A hash of the file
+ * content uploaded in this call. If provided and the uploaded content does not
+ * match this hash, an error will be returned. For more information see our
+ * Content hash https://www.dropbox.com/developers/reference/content-hash page.
  */
 
 /**
@@ -2390,7 +2401,7 @@ only present when needed to discriminate between multiple possible subtypes.
  * @property {FilePropertiesInvalidPropertyGroupError} [properties_error] -
  * Available if .tag is properties_error. The supplied property group is
  * invalid. The file has uploaded without property groups.
- * @property {('lookup_failed'|'path'|'properties_error'|'too_many_shared_folder_targets'|'too_many_write_operations'|'concurrent_session_data_not_allowed'|'concurrent_session_not_closed'|'concurrent_session_missing_data'|'payload_too_large'|'other')} .tag - Tag identifying the union variant.
+ * @property {('lookup_failed'|'path'|'properties_error'|'too_many_shared_folder_targets'|'too_many_write_operations'|'concurrent_session_data_not_allowed'|'concurrent_session_not_closed'|'concurrent_session_missing_data'|'payload_too_large'|'content_hash_mismatch'|'other')} .tag - Tag identifying the union variant.
  */
 
 /**
@@ -2417,11 +2428,15 @@ only present when needed to discriminate between multiple possible subtypes.
  * the current session.
  * @property {FilesUploadSessionType} [session_type] - Type of upload session
  * you want to start. If not specified, default is UploadSessionType.sequential.
+ * @property {string} [content_hash] - NOT YET SUPPORTED. A hash of the file
+ * content uploaded in this call. If provided and the uploaded content does not
+ * match this hash, an error will be returned. For more information see our
+ * Content hash https://www.dropbox.com/developers/reference/content-hash page.
  */
 
 /**
  * @typedef {Object} FilesUploadSessionStartError
- * @property {('concurrent_session_data_not_allowed'|'concurrent_session_close_not_allowed'|'payload_too_large'|'other')} .tag - Tag identifying the union variant.
+ * @property {('concurrent_session_data_not_allowed'|'concurrent_session_close_not_allowed'|'payload_too_large'|'content_hash_mismatch'|'other')} .tag - Tag identifying the union variant.
  */
 
 /**

lib/types.js

@@ -1,6 +1,6 @@
 {
     "name": "dropbox",
-    "version": "10.24.0",
+    "version": "10.25.0",
     "registry": "npm",
     "description": "The Dropbox JavaScript SDK is a lightweight, promise based interface to the Dropbox v2 API that works in both nodejs and browser environments.",
     "main": "cjs/index.js",

package-lock.json

@@ -1680,10 +1680,6 @@
     export type BaseTagError = BaseTagErrorPath | BaseTagErrorOther;
 
     export interface CommitInfo {
-      /**
-       * The file contents to be uploaded.
-       */
-      contents?: Object;
       /**
        * Path in the user's Dropbox to save the file.
        */
@@ -1720,13 +1716,6 @@
       strict_conflict?: boolean;
     }
 
-    export interface CommitInfoWithProperties extends CommitInfo {
-      /**
-       * The file contents to be uploaded.
-       */
-      contents?: Object;
-    }
-
     export interface ContentSyncSetting {
       /**
        * Id of the item this setting is applied to.
@@ -4815,6 +4804,20 @@
       entries: Array<UnlockFileArg>;
     }
 
+    export interface UploadArg extends CommitInfo {
+      /**
+       * The file contents to be uploaded.
+       */
+      contents?: Object;
+      /**
+       * NOT YET SUPPORTED. A hash of the file content uploaded in this call. If
+       * provided and the uploaded content does not match this hash, an error
+       * will be returned. For more information see our [Content hash]{@link
+       * https://www.dropbox.com/developers/reference/content-hash} page.
+       */
+      content_hash?: Sha256HexHash;
+    }
+
     /**
      * Unable to save the uploaded contents to a file.
      */
@@ -4838,13 +4841,19 @@
       '.tag': 'payload_too_large';
     }
 
+    /**
+     * The content received by the Dropbox server in this call does not match
+     * the provided content hash.
+     */
+    export interface UploadErrorContentHashMismatch {
+      '.tag': 'content_hash_mismatch';
+    }
+
     export interface UploadErrorOther {
       '.tag': 'other';
     }
 
-    export type UploadError = UploadErrorPath | UploadErrorPropertiesError | UploadErrorPayloadTooLarge | UploadErrorOther;
-
-    export type UploadErrorWithProperties = UploadError;
+    export type UploadError = UploadErrorPath | UploadErrorPropertiesError | UploadErrorPayloadTooLarge | UploadErrorContentHashMismatch | UploadErrorOther;
 
     export interface UploadSessionAppendArg {
       /**
@@ -4859,8 +4868,25 @@
        * Defaults to False.
        */
       close?: boolean;
+      /**
+       * NOT YET SUPPORTED. A hash of the file content uploaded in this call. If
+       * provided and the uploaded content does not match this hash, an error
+       * will be returned. For more information see our [Content hash]{@link
+       * https://www.dropbox.com/developers/reference/content-hash} page.
+       */
+      content_hash?: Sha256HexHash;
     }
 
+    /**
+     * The content received by the Dropbox server in this call does not match
+     * the provided content hash.
+     */
+    export interface UploadSessionAppendErrorContentHashMismatch {
+      '.tag': 'content_hash_mismatch';
+    }
+
+    export type UploadSessionAppendError = UploadSessionLookupError | UploadSessionAppendErrorContentHashMismatch;
+
     export interface UploadSessionCursor {
       /**
        * The file contents to be uploaded.
@@ -4891,6 +4917,13 @@
        * Contains the path and other optional modifiers for the commit.
        */
       commit: CommitInfo;
+      /**
+       * NOT YET SUPPORTED. A hash of the file content uploaded in this call. If
+       * provided and the uploaded content does not match this hash, an error
+       * will be returned. For more information see our [Content hash]{@link
+       * https://www.dropbox.com/developers/reference/content-hash} page.
+       */
+      content_hash?: Sha256HexHash;
     }
 
     export interface UploadSessionFinishBatchArg {
@@ -5014,11 +5047,19 @@
       '.tag': 'payload_too_large';
     }
 
+    /**
+     * The content received by the Dropbox server in this call does not match
+     * the provided content hash.
+     */
+    export interface UploadSessionFinishErrorContentHashMismatch {
+      '.tag': 'content_hash_mismatch';
+    }
+
     export interface UploadSessionFinishErrorOther {
       '.tag': 'other';
     }
 
-    export type UploadSessionFinishError = UploadSessionFinishErrorLookupFailed | UploadSessionFinishErrorPath | UploadSessionFinishErrorPropertiesError | UploadSessionFinishErrorTooManySharedFolderTargets | UploadSessionFinishErrorTooManyWriteOperations | UploadSessionFinishErrorConcurrentSessionDataNotAllowed | UploadSessionFinishErrorConcurrentSessionNotClosed | UploadSessionFinishErrorConcurrentSessionMissingData | UploadSessionFinishErrorPayloadTooLarge | UploadSessionFinishErrorOther;
+    export type UploadSessionFinishError = UploadSessionFinishErrorLookupFailed | UploadSessionFinishErrorPath | UploadSessionFinishErrorPropertiesError | UploadSessionFinishErrorTooManySharedFolderTargets | UploadSessionFinishErrorTooManyWriteOperations | UploadSessionFinishErrorConcurrentSessionDataNotAllowed | UploadSessionFinishErrorConcurrentSessionNotClosed | UploadSessionFinishErrorConcurrentSessionMissingData | UploadSessionFinishErrorPayloadTooLarge | UploadSessionFinishErrorContentHashMismatch | UploadSessionFinishErrorOther;
 
     /**
      * The upload session ID was not found or has expired. Upload sessions are
@@ -5111,6 +5152,13 @@
        * UploadSessionType.sequential.
        */
       session_type?: UploadSessionType;
+      /**
+       * NOT YET SUPPORTED. A hash of the file content uploaded in this call. If
+       * provided and the uploaded content does not match this hash, an error
+       * will be returned. For more information see our [Content hash]{@link
+       * https://www.dropbox.com/developers/reference/content-hash} page.
+       */
+      content_hash?: Sha256HexHash;
     }
 
     /**
@@ -5134,11 +5182,19 @@
       '.tag': 'payload_too_large';
     }
 
+    /**
+     * The content received by the Dropbox server in this call does not match
+     * the provided content hash.
+     */
+    export interface UploadSessionStartErrorContentHashMismatch {
+      '.tag': 'content_hash_mismatch';
+    }
+
     export interface UploadSessionStartErrorOther {
       '.tag': 'other';
     }
 
-    export type UploadSessionStartError = UploadSessionStartErrorConcurrentSessionDataNotAllowed | UploadSessionStartErrorConcurrentSessionCloseNotAllowed | UploadSessionStartErrorPayloadTooLarge | UploadSessionStartErrorOther;
+    export type UploadSessionStartError = UploadSessionStartErrorConcurrentSessionDataNotAllowed | UploadSessionStartErrorConcurrentSessionCloseNotAllowed | UploadSessionStartErrorPayloadTooLarge | UploadSessionStartErrorContentHashMismatch | UploadSessionStartErrorOther;
 
     export interface UploadSessionStartResult {
       /**