Spec Update 02/18/2021 (#30)

Change Notes:

Files Namespace:
- Add paper/create, paper/update routes
- Add PaperCreateArg, PaperCreateResult, PaperCreateArg, PaperCreateResult, PaperUpdateArg, PaperUpdateResult structs
- Add ImportFormat, PaperContentError, PaperCreateError, PaperDocUpdatePolicy, PaperUpdateError unions
- Update Comments

Team Log Generated Namespace:
- Add GovernancePolicyContentDisposedDetails, GovernancePolicyContentDisposedType structs
- Add DispositionActionType union
- Update ClassificationType union to include pii
- Update EventDetails union to include governance_policy_content_disposed_details
- Update EventType union to include governance_policy_content_disposed
- Update EventTypeArg uniont to include governance_policy_content_disposed
- Update Comments

Team Reports Namespace:
- Deprecate reports/get_storage, reports/get_activity, reports/get_membership, reports/get_devices routes

Co-authored-by: jorges26 <[email protected]>

Author: Jorge Santoyo

files.stone

@@ -725,8 +725,7 @@ struct ExportMetadata
         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."
+        "If the file is a Paper doc, this gives the latest doc revision which can be used in :route:`paper/update`."
 
     example default
         name = "Prime_Numbers.xlsx"
@@ -3070,3 +3069,148 @@ route get_file_lock_batch (LockFileBatchArg, LockFileBatchResult, LockFileError)
 #
 # END OF FILE LOCKING
 #
+
+
+#
+# Paper routes
+#
+
+union ImportFormat
+    "The import format of the incoming Paper doc content."
+
+    html
+        "The provided data is interpreted as standard HTML."
+    markdown
+        "The provided data is interpreted as markdown."
+    plain_text
+        "The provided data is interpreted as plain text."
+
+
+union PaperContentError
+    insufficient_permissions
+        "Your account does not have permissions to edit Paper docs."
+    content_malformed
+        "The provided content was malformed and cannot be imported to Paper."
+    doc_length_exceeded
+        "The Paper doc would be too large, split the content into multiple docs."
+    image_size_exceeded
+        "The imported document contains an image that is too large. The current limit is 1MB.
+        This only applies to HTML with data URI."
+
+
+struct PaperCreateArg
+
+    path Path
+        "The fully qualified path to the location in the user's Dropbox where the Paper Doc should be created.
+        This should include the document's title and end with .paper."
+    import_format ImportFormat
+        "The format of the provided data."
+
+    example default
+        path = "/Paper Docs/New Doc.paper"
+        import_format = html
+
+
+struct PaperCreateResult
+
+    url String
+        "URL to open the Paper Doc."
+    result_path String
+        "The fully qualified path the Paper Doc was actually created at."
+    file_id FileId
+        "The id to use in Dropbox APIs when referencing the Paper Doc."
+    paper_revision Int64
+        "The current doc revision."
+
+    example default
+        url = "https://www.dropbox.com/scl/xxx.paper?dl=0"
+        result_path = "/Paper Docs/New Doc.paper"
+        file_id = "id:a4ayc_80_OEAAAAAAAAAXw"
+        paper_revision = 1
+
+
+union PaperCreateError extends PaperContentError
+    invalid_path
+        "The file could not be saved to the specified location."
+    email_unverified
+        "The user's email must be verified to create Paper docs."
+    invalid_file_extension
+        "The file path must end in .paper."
+    paper_disabled
+        "Paper is disabled for your team."
+
+union PaperDocUpdatePolicy
+    update
+        "Sets the doc content to the provided content if the provided paper_revision matches the latest doc revision.
+        Otherwise, returns an error."
+    overwrite
+        "Sets the doc content to the provided content without checking paper_revision."
+    prepend
+        "Adds the provided content to the beginning of the doc without checking paper_revision."
+    append
+        "Adds the provided content to the end of the doc without checking paper_revision."
+
+
+struct PaperUpdateArg
+
+    path WritePathOrId
+        "Path in the user's Dropbox to update. The path must correspond to a Paper doc or an error will be returned."
+    import_format ImportFormat
+        "The format of the provided data."
+    doc_update_policy PaperDocUpdatePolicy
+        "How the provided content should be applied to the doc."
+    paper_revision Int64?
+        "The latest doc revision. Required when doc_update_policy is update.
+        This value must match the current revision of the doc or error revision_mismatch will be returned."
+
+    example default
+        path = "/Paper Docs/My Doc.paper"
+        import_format = html
+        doc_update_policy = update
+        paper_revision = 123
+
+
+struct PaperUpdateResult
+
+    paper_revision Int64
+        "The current doc revision."
+
+    example default
+        paper_revision = 124
+
+
+union PaperUpdateError extends PaperContentError
+    path LookupError
+    revision_mismatch
+        "The provided revision does not match the document head."
+    doc_archived
+        "This operation is not allowed on archived Paper docs."
+    doc_deleted
+        "This operation is not allowed on deleted Paper docs."
+
+
+route paper/create (PaperCreateArg, PaperCreateResult, PaperCreateError)
+    "
+    Creates a new Paper doc with the provided content.
+    "
+
+    attrs
+        is_preview = true
+        style = "upload"
+        scope = "files.content.write"
+
+
+route paper/update (PaperUpdateArg, PaperUpdateResult, PaperUpdateError)
+    "
+    Updates an existing Paper doc with the provided content.
+    "
+
+    attrs
+        is_preview = true
+        style = "upload"
+        scope = "files.content.write"
+
+
+#
+# End of Paper routes
+#

team_log_generated.stone

@@ -323,7 +323,8 @@ union ClassificationPolicyEnumWrapper
     enabled
 
 union ClassificationType
-    "The type of classification (currently only PII)"
+    "The type of classification (currently only personal information)"
+    personal_information
     pii
 
 union ComputerBackupPolicy
@@ -349,6 +350,10 @@ union DeviceUnlinkPolicy
     keep
     remove
 
+union DispositionActionType
+    automatic_delete
+    automatic_permanently_delete
+
 union DownloadPolicyType
     "Shared content downloads policy"
     allow
@@ -2025,6 +2030,24 @@ struct GovernancePolicyAddFolderFailedDetails
         folder = "abc"
         reason = "abc"
 
+struct GovernancePolicyContentDisposedDetails
+    "Content disposed."
+
+    governance_policy_id String
+        "Policy ID."
+    name String
+        "Policy name."
+    policy_type PolicyType?
+        "Policy type."
+    disposition_type DispositionActionType
+        "Disposition type."
+
+    example default
+        governance_policy_id = "abc"
+        name = "abc"
+        policy_type = retention
+        disposition_type = automatic_delete
+
 struct GovernancePolicyCreateDetails
     "Activated a new policy."
 
@@ -6398,6 +6421,7 @@ union EventDetails
     file_unresolve_comment_details FileUnresolveCommentDetails
     governance_policy_add_folders_details GovernancePolicyAddFoldersDetails
     governance_policy_add_folder_failed_details GovernancePolicyAddFolderFailedDetails
+    governance_policy_content_disposed_details GovernancePolicyContentDisposedDetails
     governance_policy_create_details GovernancePolicyCreateDetails
     governance_policy_delete_details GovernancePolicyDeleteDetails
     governance_policy_edit_details_details GovernancePolicyEditDetailsDetails
@@ -6957,6 +6981,12 @@ struct GovernancePolicyAddFolderFailedType
     example default
         description = "(data_governance) Couldn't add a folder to a policy"
 
+struct GovernancePolicyContentDisposedType
+    description String
+
+    example default
+        description = "(data_governance) Content disposed"
+
 struct GovernancePolicyCreateType
     description String
 
@@ -9637,6 +9667,8 @@ union EventType
         "(data_governance) Added folders to policy"
     governance_policy_add_folder_failed GovernancePolicyAddFolderFailedType
         "(data_governance) Couldn't add a folder to a policy"
+    governance_policy_content_disposed GovernancePolicyContentDisposedType
+        "(data_governance) Content disposed"
     governance_policy_create GovernancePolicyCreateType
         "(data_governance) Activated a new policy"
     governance_policy_delete GovernancePolicyDeleteType
@@ -10561,6 +10593,8 @@ union EventTypeArg
         "(data_governance) Added folders to policy"
     governance_policy_add_folder_failed
         "(data_governance) Couldn't add a folder to a policy"
+    governance_policy_content_disposed
+        "(data_governance) Content disposed"
     governance_policy_create
         "(data_governance) Activated a new policy"
     governance_policy_delete

team_reports.stone

@@ -71,7 +71,8 @@ struct GetStorageReport extends BaseDfbReport
         If there is no data for a day, the storage summary will be empty."
 
 route reports/get_storage(DateRange, GetStorageReport, DateRangeError) deprecated
-    "Retrieves reporting data about a team's storage usage."
+    "Retrieves reporting data about a team's storage usage.
+    Deprecated: Will be removed on July 1st 2021."
     attrs
         auth = "team"
         scope = "team_info.read"
@@ -116,7 +117,8 @@ struct GetActivityReport extends BaseDfbReport
         "Array of the total number of views to shared links created by the team."
 
 route reports/get_activity(DateRange, GetActivityReport, DateRangeError) deprecated
-    "Retrieves reporting data about a team's user activity."
+    "Retrieves reporting data about a team's user activity.
+    Deprecated: Will be removed on July 1st 2021."
     attrs
         auth = "team"
         scope = "team_info.read"
@@ -144,7 +146,8 @@ struct GetMembershipReport extends BaseDfbReport
 
 
 route reports/get_membership(DateRange, GetMembershipReport, DateRangeError) deprecated
-    "Retrieves reporting data about a team's membership."
+    "Retrieves reporting data about a team's membership.
+    Deprecated: Will be removed on July 1st 2021."
     attrs
         auth = "team"
         scope = "team_info.read"
@@ -191,7 +194,9 @@ struct GetDevicesReport extends BaseDfbReport
 
 
 route reports/get_devices(DateRange, GetDevicesReport, DateRangeError) deprecated
-    "Retrieves reporting data about a team's linked devices."
+    "Retrieves reporting data about a team's linked devices.
+    Deprecated: Will be removed on July 1st 2021."
+
     attrs
         auth = "team"
         scope = "team_info.read"