Spec Update 02/10/2021 (#29)

Change Notes:

Files Namespace:

- Update ExportInfo struct to include export_options
- Update ExportError union to include invalid_export_format
- Update ExportArg struct to include export_format
- Update ExportMetadata to include paper_revision
- Update GetTemporaryLinkError union to include not_allowed
- Update Comments

Team Log Generated Namespace:

- Add RecipicientsConfiguration, ObjectLabelAddedDetails, ObjectLabelRemoveDetails, ObjectLabelUpdatedValueDetails, ObjectLabelAddedType, ObjectLabelRemoved, and ObjectLabelUpdatedValue structs
- Add AlertRecipientsSettingType, AdminAlertingAlertSensitivity, and LabelType unions
- Update AdminAlertSeverityEnum to include sensitivity_level and recipients_settings
- Update PlacementRestriction union to include uk_only
- Update EventDetails union to include object_label_added_details, object_label_removed_details and object_label_updated_value_details
- Update EventType union to include object_label_added, object_label_removed and object_label_updated_value
- Update EventTypeArg union to include object_label_added, object_label_removed, and object_label_updated_value
- Update Examples

Author: rogebrd

files.stone

@@ -123,6 +123,10 @@ struct ExportInfo
     export_as String?
         "Format to which the file can be exported to."
 
+    export_options List(String)?
+        "Additional formats to which the file can be exported. These values can be
+        specified as the export_format in /files/export."
+
     example default
         export_as = "xlsx"
 
@@ -683,6 +687,8 @@ union ExportError
     path LookupError
     non_exportable
         "This file type cannot be exported. Use :route:`download` instead."
+    invalid_export_format
+        "The specified export format is not a valid option for this file type."
     retry_error
         "The exportable content is not yet available. Please retry later."
 
@@ -692,6 +698,13 @@ struct ExportArg
     path ReadPath
         "The path of the file to be exported."
 
+    export_format String?
+        "The file format to which the file should be exported.
+        This must be one of the formats listed in the file's
+        export_options returned by :route:`get_metadata`.
+        If none is specified, the default format (specified
+        in export_as in file metadata) will be used."
+
     example default
         path = "/Homework/math/Prime_Numbers.gsheet"
 
@@ -711,6 +724,10 @@ struct ExportMetadata
         "A hash based on the exported file content. This field can be used to verify data integrity. Similar to content hash.
         For more information see our :link:`Content hash https://www.dropbox.com/developers/reference/content-hash` page."
 
+    paper_revision Int64?
+        # TODO(jessk): after /files/paper/update is made public, add "which can be used in :route:`paper/update`."
+        "If the file is a Paper doc, this gives the latest doc revision."
+
     example default
         name = "Prime_Numbers.xlsx"
         size = 7189
@@ -773,7 +790,7 @@ union UploadSessionStartError
 union UploadSessionLookupError
     not_found
         "The upload session ID was not found or has expired. Upload sessions are
-        valid for 48 hours."
+        valid for 7 days."
     incorrect_offset UploadSessionOffsetError
         "The specified offset was incorrect. See the value for the
         correct offset. This error may occur when a previous request
@@ -818,7 +835,7 @@ union UploadSessionFinishError
 
 union UploadSessionType
     sequential
-        "Pieces of content are uploaded sequentially one after another. This is the default
+        "Pieces of data are uploaded sequentially one after another. This is the default
         behavior."
     concurrent
         "Pieces of data can be uploaded in concurrent RPCs in any order."
@@ -856,10 +873,10 @@ route upload_session/start (UploadSessionStartArg, UploadSessionStartResult, Upl
     A single request should not upload more than 150 MB. The maximum size of
     a file one can upload to an upload session is 350 GB.
 
-    An upload session can be used for a maximum of 48 hours. Attempting
+    An upload session can be used for a maximum of 7 days. Attempting
     to use an :field:`UploadSessionStartResult.session_id` with
     :route:`upload_session/append:2` or :route:`upload_session/finish` more
-    than 48 hours after its creation will return a
+    than 7 days after its creation will return a
     :field:`UploadSessionLookupError.not_found`.
 
     Calls to this endpoint will count as data transport calls for any Dropbox
@@ -922,9 +939,8 @@ struct UploadSessionCursor
     session_id String
         "The upload session ID (returned by :route:`upload_session/start`)."
     offset UInt64
-        "The amount of data that has been uploaded so far. We use this to make
-        sure upload data isn't lost or duplicated in the event of a network
-        error."
+        "Offset in bytes at which data should be appended. We use this to make
+        sure upload data isn't lost or duplicated in the event of a network error."
 
     example default
         session_id = "1234faaf0678bcde"
@@ -2213,7 +2229,7 @@ route get_thumbnail(ThumbnailArg, FileMetadata, ThumbnailError)
     "Get a thumbnail for an image.
 
     This method currently supports files with the following file extensions:
-    jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
+    jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB
     in size won't be converted to a thumbnail."
 
     attrs
@@ -2227,7 +2243,7 @@ route get_thumbnail_batch(GetThumbnailBatchArg, GetThumbnailBatchResult, GetThum
     "Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch.
 
     This method currently supports files with the following file extensions:
-    jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
+    jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB
     in size won't be converted to a thumbnail."
 
     attrs
@@ -2320,7 +2336,11 @@ struct ThumbnailV2Arg
 
 
 route get_thumbnail:2(ThumbnailV2Arg, PreviewResult, ThumbnailV2Error)
-    "Get a thumbnail for a file."
+    "Get a thumbnail for an image.
+
+    This method currently supports files with the following file extensions:
+    jpg, jpeg, png, tiff, tif, gif, webp, ppm and bmp. Photos that are larger than 20MB
+    in size won't be converted to a thumbnail."
 
     attrs
         host = "content"
@@ -2499,6 +2519,10 @@ union GetTemporaryLinkError
         their email address :link:`here https://www.dropbox.com/help/317`."
     unsupported_file
         "Cannot get temporary link to this file type; use :route:`export` instead."
+    not_allowed
+        "The user is not allowed to request a temporary link to the specified file.
+        For example, this can occur if the file is restricted or if the user's links
+        are :link:`banned https://help.dropbox.com/files-folders/share/banned-links`."
 
 route get_temporary_link(GetTemporaryLinkArg, GetTemporaryLinkResult, GetTemporaryLinkError)
     "Get a temporary link to stream content of a file. This link will expire in four hours and

team_log_generated.stone

@@ -206,14 +206,58 @@ union AdminAlertSeverityEnum
 struct AdminAlertingAlertConfiguration
     "Alert configurations"
 
-    alert_state AdminAlertingAlertStatePolicy
+    alert_state AdminAlertingAlertStatePolicy?
         "Alert state."
+    sensitivity_level AdminAlertingAlertSensitivity?
+        "Sensitivity level."
+    recipients_settings RecipientsConfiguration?
+        "Recipient settings."
 
     example default
         alert_state = off
+        sensitivity_level = invalid
+        recipients_settings = default
 
     example default2
         alert_state = off
+        sensitivity_level = invalid
+        recipients_settings = default2
+
+struct RecipientsConfiguration
+    "Recipients Configuration"
+
+    recipient_setting_type AlertRecipientsSettingType?
+        "Recipients setting type."
+    emails List(EmailAddress)?
+        "A list of user emails to notify."
+    groups List(String)?
+        "A list of groups to notify."
+
+    example default
+        recipient_setting_type = invalid
+        emails = ["[email protected]"]
+        groups = ["abc"]
+
+    example default2
+        recipient_setting_type = invalid
+        emails = ["[email protected]"]
+        groups = ["xyz"]
+
+union AlertRecipientsSettingType
+    "Alert recipients setting type"
+    custom_list
+    invalid
+    none
+    team_admins
+
+union AdminAlertingAlertSensitivity
+    "Alert sensitivity"
+    high
+    highest
+    invalid
+    low
+    lowest
+    medium
 
 union AdminAlertingAlertStatePolicy
     "Policy for controlling whether an alert can be triggered or not"
@@ -528,6 +572,10 @@ union IntegrationPolicy
     disabled
     enabled
 
+union LabelType
+    "Label type"
+    personal_information
+
 union LockStatus
     "File lock status"
     locked
@@ -614,6 +662,7 @@ union PlacementRestriction
     europe_only
     japan_only
     none
+    uk_only
 
 union PolicyType
     disposition
@@ -2672,6 +2721,33 @@ struct FolderOverviewItemUnpinnedDetails
         folder_overview_location_asset = 3
         pinned_items_asset_indices = [3]
 
+struct ObjectLabelAddedDetails
+    "Added a label."
+
+    label_type LabelType
+        "Labels mark a file or folder."
+
+    example default
+        label_type = personal_information
+
+struct ObjectLabelRemovedDetails
+    "Removed a label."
+
+    label_type LabelType
+        "Labels mark a file or folder."
+
+    example default
+        label_type = personal_information
+
+struct ObjectLabelUpdatedValueDetails
+    "Updated a label's value."
+
+    label_type LabelType
+        "Labels mark a file or folder."
+
+    example default
+        label_type = personal_information
+
 struct RewindFolderDetails
     "Rewound a folder."
 
@@ -6390,6 +6466,9 @@ union EventDetails
     folder_overview_description_changed_details FolderOverviewDescriptionChangedDetails
     folder_overview_item_pinned_details FolderOverviewItemPinnedDetails
     folder_overview_item_unpinned_details FolderOverviewItemUnpinnedDetails
+    object_label_added_details ObjectLabelAddedDetails
+    object_label_removed_details ObjectLabelRemovedDetails
+    object_label_updated_value_details ObjectLabelUpdatedValueDetails
     rewind_folder_details RewindFolderDetails
     file_request_change_details FileRequestChangeDetails
     file_request_close_details FileRequestCloseDetails
@@ -7286,6 +7365,24 @@ struct FolderOverviewItemUnpinnedType
     example default
         description = "(file_operations) Unpinned item from folder overview"
 
+struct ObjectLabelAddedType
+    description String
+
+    example default
+        description = "(file_operations) Added a label"
+
+struct ObjectLabelRemovedType
+    description String
+
+    example default
+        description = "(file_operations) Removed a label"
+
+struct ObjectLabelUpdatedValueType
+    description String
+
+    example default
+        description = "(file_operations) Updated a label's value"
+
 struct RewindFolderType
     description String
 
@@ -9676,6 +9773,12 @@ union EventType
         "(file_operations) Pinned item to folder overview"
     folder_overview_item_unpinned FolderOverviewItemUnpinnedType
         "(file_operations) Unpinned item from folder overview"
+    object_label_added ObjectLabelAddedType
+        "(file_operations) Added a label"
+    object_label_removed ObjectLabelRemovedType
+        "(file_operations) Removed a label"
+    object_label_updated_value ObjectLabelUpdatedValueType
+        "(file_operations) Updated a label's value"
     rewind_folder RewindFolderType
         "(file_operations) Rewound a folder"
     file_request_change FileRequestChangeType
@@ -10594,6 +10697,12 @@ union EventTypeArg
         "(file_operations) Pinned item to folder overview"
     folder_overview_item_unpinned
         "(file_operations) Unpinned item from folder overview"
+    object_label_added
+        "(file_operations) Added a label"
+    object_label_removed
+        "(file_operations) Removed a label"
+    object_label_updated_value
+        "(file_operations) Updated a label's value"
     rewind_folder
         "(file_operations) Rewound a folder"
     file_request_change