Update public spec.

- Files
  - Add save_url endpoint for saving online content to your Dropbox.
- Shared folders
  - Add viewer_no_comment to AccessLevel.
  - Add is_owner to GroupInfo.
  - Change return type of SharePathError.already_shared from Void to SharedFolderMetadata.
  - Add leave_a_copy parameter to relinquish_folder_membership endpoint.
  - Change relinquish_folder_membership to return async job ID when leaving a copy.
  - Add relinquish_folder_membership_error to JobError.
- Business endpoints
  - Add membership_type to MemberProfile.
  - Add keep_account parameter to members/remove endpoint.
  - Add cannot_keep_account_and_transfer and cannot_keep_account_and_delete_data to MembersRemoveError.

Author: Karl Rieb

auth.stone

@@ -7,6 +7,8 @@ union AuthError
         "The access token is invalid."
     invalid_select_user
         "The user specified in 'Dropbox-API-Select-User' is no longer on the team."
+    invalid_select_admin
+        "The user specified in 'Dropbox-API-Select-Admin' is not a Dropbox Business team admin."
     other*
         "An unspecified error."
 

files.stone

@@ -1,17 +1,18 @@
 namespace files
     "This namespace contains endpoints and data types for basic file operations."
 
+import async
 import common
 import users
 import properties
 
 alias Id = String(min_length=1)
-alias Path = String(pattern="/.*")
-alias PathOrId = String(pattern="(/|id:).*")
-alias PathR = String(pattern="(/.*)?")               # A path that can be the root path ("").
+alias Path = String(pattern="/(.|[\\r\\n])*")
+alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*")
+alias PathR = String(pattern="(/(.|[\\r\\n])*)?")               # A path that can be the root path ("").
 alias Rev = String(min_length=9, pattern="[0-9a-f]+") # TODO: Change pattern to "rev:[0-9a-f]{9,}"
 alias ListFolderCursor = String(min_length=1)
-alias ReadPath = String(pattern="((/|id:).*)|(rev:[0-9a-f]{9,})")
+alias ReadPath = String(pattern="(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})")
 
 #
 # Metadata definitions and route
@@ -282,7 +283,7 @@ struct ListFolderLongpollArg
 struct ListFolderLongpollResult
     changes Boolean
         "Indicates whether new changes are available. If true, call
-        :route:`list_folder` to retrieve the changes."
+        :route:`list_folder/continue` to retrieve the changes."
     backoff UInt64?
         "If present, backoff for at least this many seconds before calling
         :route:`list_folder/longpoll` again."
@@ -298,10 +299,11 @@ union ListFolderLongpollError
 
 route list_folder/longpoll (ListFolderLongpollArg, ListFolderLongpollResult, ListFolderLongpollError)
     "A longpoll endpoint to wait for changes on an account. In conjunction with
-    :route:`list_folder`, this call gives you a low-latency way to monitor an
-    account for file changes. The connection will block until there are changes
-    available or a timeout occurs. This endpoint is useful mostly for client-side
-    apps. If you're looking for server-side notifications, check out our
+    :route:`list_folder/continue`, this call gives you a low-latency way to
+    monitor an account for file changes. The connection will block until there
+    are changes available or a timeout occurs. This endpoint is useful mostly
+    for client-side apps. If you're looking for server-side notifications,
+    check out our
     :link:`webhooks documentation https://www.dropbox.com/developers/reference/webhooks`."
     attrs
         host="notify"
@@ -1025,7 +1027,6 @@ union RestoreError
 route restore(RestoreArg, FileMetadata, RestoreError)
     "Restore a file to a specific revision"
 
-
 #
 # Temporary link
 #
@@ -1124,3 +1125,48 @@ union SaveCopyReferenceError
 
 route copy_reference/save(SaveCopyReferenceArg, SaveCopyReferenceResult, SaveCopyReferenceError)
     "Save a copy reference returned by :route:`copy_reference/get` to the user's Dropbox."
+
+#
+# Save URL
+#
+
+struct SaveUrlArg
+    path Path
+        "The path in Dropbox where the URL will be saved to."
+    url String
+        "The URL to be saved."
+
+    example default
+        path = "/a.txt"
+        url = "http://example.com/a.txt"
+
+union SaveUrlResult extends async.LaunchResultBase
+    complete FileMetadata
+        "Metadata of the file where the URL is saved to."
+
+union SaveUrlError
+    path WriteError
+    download_failed
+        "Failed downloading the given URL."
+    invalid_url
+        "The given URL is invalid."
+    not_found
+        "The file where the URL is saved to no longer exists."
+    other*
+
+route save_url(SaveUrlArg, SaveUrlResult, SaveUrlError)
+    "Save a specified URL into a file in user's Dropbox. If the given path already
+    exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt)."
+
+#
+# Save URL Job
+#
+
+union SaveUrlJobStatus extends async.PollResultBase
+    complete FileMetadata
+        "Metadata of the file where the URL is saved to."
+    failed SaveUrlError
+
+route save_url/check_job_status(async.PollArg, SaveUrlJobStatus, async.PollError)
+    "Check the status of a :route:`save_url` job."
+

sharing_folders.stone

@@ -5,7 +5,7 @@ namespace sharing
 import async
 import common
 import files
-import team
+import team_common
 import users
 
 alias DropboxId = String(min_length=1)
@@ -21,6 +21,9 @@ union AccessLevel
         "The collaborator can both view and edit the shared folder."
     viewer
         "The collaborator can only view the shared folder."
+    viewer_no_comment
+        "The collaborator can only view the shared folder and does
+        not have any access to comments."
     other*
 
 struct FolderPolicy
@@ -232,12 +235,14 @@ struct InviteeMembershipInfo extends MembershipInfo
         access_type = viewer
         permissions = []
 
-struct GroupInfo extends team.GroupSummary
+struct GroupInfo extends team_common.GroupSummary
     "The information about a group. Groups is a way to manage a list of users
      who need same access permission to the shared folder."
 
-    group_type team.GroupType
+    group_type team_common.GroupType
         "The type of group."
+    is_owner Boolean
+        "If the current user is an owner of the group."
     same_team Boolean
         "If the group is owned by the current user's team."
 
@@ -246,6 +251,7 @@ struct GroupInfo extends team.GroupSummary
         group_id = "g:e2db7665347abcd600000000001a2b3c"
         member_count = 10
         group_type = user_managed
+        is_owner = false
         same_team = true
 
 struct GroupMembershipInfo extends MembershipInfo
@@ -544,8 +550,8 @@ union SharePathError
     inside_public_folder
         "A folder inside a public folder can't be shared this way. Use a public
         link instead."
-    already_shared
-        "Folder is already shared."
+    already_shared SharedFolderMetadata
+        "Folder is already shared. Contains metadata about the existing shared folder."
     invalid_path
         "Path is not valid."
     is_osx_package
@@ -575,14 +581,14 @@ route check_share_job_status(async.PollArg, ShareFolderJobStatus, async.PollErro
 
     Apps must have full Dropbox access to use this endpoint."
 
-# --
-
 union JobStatus extends async.PollResultBase
     complete
         "The asynchronous job has finished."
     failed JobError
         "The asynchronous job returned an error."
 
+# --
+
 union SharedFolderMemberError
     invalid_dropbox_id
         "The target dropbox_id is invalid."
@@ -598,6 +604,8 @@ union JobError
         "Error occurred while performing :route:`unshare_folder` action."
     remove_folder_member_error RemoveFolderMemberError
         "Error occurred while performing :route:`remove_folder_member` action."
+    relinquish_folder_membership_error RelinquishFolderMembershipError
+        "Error occurred while performing :route:`relinquish_folder_membership` action."
     other*
 
 route check_job_status(async.PollArg, JobStatus, async.PollError)
@@ -661,7 +669,7 @@ union TransferFolderError
     new_owner_not_a_member
         "The new designated owner is not currently a member of the shared folder."
     new_owner_unmounted
-        "The new designated owner does not have the shared folder mounted."
+        "The new designated owner has not added the folder to their Dropbox."
     new_owner_email_unverified
         "The new designated owner's e-mail address is unverified."
     team_folder
@@ -962,19 +970,24 @@ union UnmountFolderError
 
 # --
 
-route relinquish_folder_membership(RelinquishFolderMembershipArg, Void, RelinquishFolderMembershipError)
+route relinquish_folder_membership(RelinquishFolderMembershipArg, async.LaunchEmptyResult, RelinquishFolderMembershipError)
     "The current user relinquishes their membership in the designated shared
     folder and will no longer have access to the folder.  A folder owner cannot
     relinquish membership in their own folder.
 
+    This will run synchronously if leave_a_copy is false, and asynchronously
+    if leave_a_copy is true.
     Apps must have full Dropbox access to use this endpoint."
 
 struct RelinquishFolderMembershipArg
     shared_folder_id common.SharedFolderId
         "The ID for the shared folder."
+    leave_a_copy Boolean = false
+        "Keep a copy of the folder's contents upon relinquishing membership."
 
     example default
         shared_folder_id = "84528192421"
+        leave_a_copy = false
 
 union RelinquishFolderMembershipError
     access_error SharedFolderAccessError

stone_cfg.stone

@@ -0,0 +1,15 @@
+namespace stone_cfg
+
+struct Route
+
+    auth String = "user"
+        "The auth type for the route. Valid values: user, team, app, noauth."
+    host String = "meta"
+        "The server to make the request to. Valid values: meta, content,
+        and notify."
+    style String = "rpc"
+        "The RPC format to use for the request. Valid values: rpc, download,
+        and upload."
+    alpha_group String?
+        "Set if the route is part of an alpha release to the name of the
+        feature."

team.stone

@@ -27,6 +27,11 @@ union TeamMemberStatus
         "User is no longer a member of the team, but the account can be un-suspended,
         re-establishing the user as a team member."
 
+union TeamMembershipType
+    full
+        "User uses a license and has full access to team resources like the shared quota."
+    limited
+        "User does not have access to the shared quota and team admins have restricted administrative control."
 
 struct MemberProfile
     "Basic member profile."
@@ -45,13 +50,16 @@ struct MemberProfile
         "The user's status as a member of a specific team."
     name users.Name
         "Representations for a person's name."
+    membership_type TeamMembershipType
+        "The user's membership type: full (normal team member) vs limited (does not use a license; no access to the team's shared quota)."
 
     example default
         team_member_id = "dbmid:1234567"
         email = "[email protected]"
         email_verified = true
         status = active
         name = default
+        membership_type = full
 
 union UserSelectorArg
     "Argument for selecting a single user, either by team_member_id, external_id or email."

team_common.stone

@@ -1,4 +1,4 @@
-namespace team
+namespace team_common
 
 alias GroupId = String
 
@@ -17,6 +17,29 @@ struct GroupSummary
         group_id = "g:e2db7665347abcd600000000001a2b3c"
         member_count = 10
 
+
+struct AlphaGroupSummary extends GroupSummary
+    "Information about a group."
+
+    group_management_type GroupManagementType
+        "Who is allowed to manage the group."
+
+    example default
+        group_name = "Test group"
+        group_id = "g:e2db7665347abcd600000000001a2b3c"
+        member_count = 10
+        group_management_type = user_managed
+
+union GroupManagementType
+    "The group type determines how a group is managed."
+
+    company_managed
+        "A group which is managed by team admins only."
+    user_managed
+        "A group which is managed by selected users."
+    other*
+
+
 union GroupType
     "The group type determines how a group is created and managed."