avh4 / elm-dropbox / Dropbox

Dropbox API

See the official Dropbox documentation at https://www.dropbox.com/developers/documentation/http/documentation

application : { init : flags -> Url -> ( model, Platform.Cmd.Cmd msg ), update : msg -> model -> ( model, Platform.Cmd.Cmd msg ), subscriptions : model -> Platform.Sub.Sub msg, view : model -> Browser.Document msg, onAuth : AuthorizeResult -> msg } -> Platform.Program flags model (Msg msg)

This provides the simplest way to integrate Dropbox authentication. Using Dropbox.application will handle parsing the authentication response from the authentication redirect so that you don't have to do it manually.


type Msg msg

The message type for an app that uses Dropbox.program

Authorization


type alias AuthorizeRequest =
{ clientId : String
, state : Maybe String
, requireRole : Maybe Role
, forceReapprove : Basics.Bool
, disableSignup : Basics.Bool
, locale : Maybe String
, forceReauthentication : Basics.Bool 
}

Request parameters for Dropbox OAuth 2.0 authorization requests.

See https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize

Note: redirect_uri is not present here because it is provided directly to Dropbox.authorize or Dropbox.authorizationUrl.


type Role
    = Personal
    | Work

See https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize

authorize : AuthorizeRequest -> Url -> Platform.Cmd.Cmd msg

https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize


type AuthorizeResult
    = DropboxAuthorizeErr AuthorizeError
    | AuthorizeOk ({ userAuth : UserAuth, accountId : String, state : Maybe String })
    | UnknownAccessTokenErr ({ accessToken : String, tokenType : String, accountId : String, state : Maybe String })

Return value of the authorize endpoint, which is the data Dropbox returns via the redirect URL.

You can get the AuthorizeResult by using Dropbox.program, or by using parseAuthorizeResult if you need to manually parse the redirect URL.

See https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize

Note: uid is not provided because it is deprecated. See https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize


type alias AuthorizeError =
{ error : String
, errorDescription : String
, state : Maybe String 
}

Return value of the authorize endpoint when authentication fails. See AuthorizeResult.

See https://www.dropbox.com/developers/documentation/http/documentation#oauth2-authorize


type UserAuth

A user authentication token that can be used to authenticate API calls

See https://www.dropbox.com/developers/reference/auth-types#user

encodeUserAuth : UserAuth -> Json.Encode.Value

Encode a UserAuth to JSON.

You should consider the resulting value to be opaque and only read it using decodeUserAuth.

WARNING: To protect your users' security, you must not transmit the resulting value off the user's device. This function exists to allow persisting the auth token to localStorage or other storage that is local to the user's device and private to your application. You should not send this value to your own server (if you think you need that, you should use a different OAuth flow involving your Dropox app's app secret instead of using implicit grant).

decodeUserAuth : Json.Decode.Decoder UserAuth

Decode a UserAuth encoded with encodeUserAuth.

NOTE: See the security warning in encodeUserAuth.

If you have an auth token as a String and need to convert it to a UserAuth, see authorizationFromAccessToken.

authorizationUrl : AuthorizeRequest -> String -> String

The Dropbox OAuth 2.0 authorization URL. Typically you will just want to use authorize instead, which will initiate the authorization.

See https://www.dropbox.com/developers/reference/oauth-guide

redirectUriFromLocation : Url -> String

Generate a redirect URI from a Url.

Typically you will want to use Dropbox.authorize, which will do this automatically. You may want to use this if you need to manually manage the OAuth flow.

authorizationFromAccessToken : String -> UserAuth

Create a UserAuth from a Dropbox access token.

You can use this during development, using the "generated access token" from the settings page of your Dropbox app.

You should not use this in a production app. Instead, you should use the normal authorization flow and use program or parseAuthorizeResult.

parseAuthorizeResult : Url -> Maybe AuthorizeResult

Read an AuthorizeResult from the page location.

Typically you will want to use Dropbox.program instead, which will do this automatically. You may want to use this if you need to manually manage the OAuth flow.

Auth

tokenRevoke : UserAuth -> Task Http.Error ()

Disables the access token used to authenticate the call.

See https://www.dropbox.com/developers/documentation/http/documentation#auth-token-revoke

Files


type Metadata
    = FileMeta FileMetadata
    | FolderMeta FolderMetadata
    | DeletedMeta DeletedMetadata

Metadata union type


type alias FileMetadata =
{ name : String
, id : String
, clientModified : Time.Posix
, serverModified : Time.Posix
, rev : String
, size : Basics.Int
, pathLower : Maybe String
, pathDisplay : Maybe String
, mediaInfo : Maybe MediaInfo
, sharingInfo : Maybe FileSharingInfo
, propertyGroups : Maybe (List PropertyGroup)
, hasExplicitSharedMembers : Maybe Basics.Bool
, contentHash : Maybe String 
}

File metadata

WARNING: elm-dropbox may give the incorrect values for size, since Elm currently does not provide a way to parse and represent 64-bit integers.


type alias FolderMetadata =
{ name : String
, id : String
, pathLower : Maybe String
, pathDisplay : Maybe String
, sharingInfo : Maybe FolderSharingInfo
, propertyGroups : Maybe (List PropertyGroup) 
}

Folder metadata


type alias DeletedMetadata =
{ name : String
, pathLower : Maybe String
, pathDisplay : Maybe String 
}

Deleted item metadata

download : UserAuth -> DownloadRequest -> Task DownloadError DownloadResponse

Download a file from a user's Dropbox.

See https://www.dropbox.com/developers/documentation/http/documentation#files-download


type alias DownloadRequest =
{ path : String }

Request parameteres for download

Note: there is no rev field because it is deprecated. See https://www.dropbox.com/developers/documentation/http/documentation#files-download


type alias DownloadResponse =
{ content : String
, name : String
, id : String
, clientModified : Time.Posix
, serverModified : Time.Posix
, rev : String
, size : Basics.Int
, pathLower : Maybe String
, pathDisplay : Maybe String
, mediaInfo : Maybe MediaInfo
, sharingInfo : Maybe FileSharingInfo
, propertyGroups : Maybe (List PropertyGroup)
, hasExplicitSharedMembers : Maybe Basics.Bool
, contentHash : Maybe String 
}

Return value for download

WARNING: elm-dropbox may give the incorrect values for size, since Elm currently does not provide a way to parse and represent 64-bit integers.


type DownloadError
    = PathDownloadError LookupError
    | OtherDownloadError String Json.Encode.Value
    | OtherDownloadFailure Http.Error

See https://www.dropbox.com/developers/documentation/http/documentation#files-download


type LookupError
    = MalformedPathLookup (Maybe String)
    | NotFound
    | NotFile
    | NotFolder
    | RestrictedContent
    | OtherLookupError String Json.Encode.Value

See https://www.dropbox.com/developers/documentation/http/documentation#files-download

upload : UserAuth -> UploadRequest -> Task UploadError FileMetadata

Create a new file with the contents provided in the request.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias UploadRequest =
{ path : String
, mode : WriteMode
, autorename : Basics.Bool
, clientModified : Maybe Time.Posix
, mute : Basics.Bool
, content : String 
}

Request parameters for upload


type WriteMode
    = Add
    | Overwrite
    | Update String

Your intent when writing a file to some path. See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type UploadError
    = Path UploadWriteFailed
    | OtherUploadError String Json.Encode.Value
    | OtherUploadFailure Http.Error

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias UploadWriteFailed =
{ reason : WriteError
, uploadSessionId : String 
}

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type WriteError
    = MalformedPathWrite (Maybe String)
    | Conflict WriteConflictError
    | NoWritePermission
    | InsufficientSpace
    | DisallowedName
    | TeamFolder
    | OtherWriteError String Json.Encode.Value

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload

listFolder : UserAuth -> ListFolderRequest -> Task ListFolderError ListFolderResponse

Begin listing the contents of a folder.

See https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder

listFolderContinue : UserAuth -> ListFolderContinueRequest -> Task ListFolderContinueError ListFolderResponse

See https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue


type alias ListFolderRequest =
{ path : String
, recursive : Basics.Bool
, includeMediaInfo : Basics.Bool
, includeDeleted : Basics.Bool
, includeHasExplicitSharedMembers : Basics.Bool 
}

Request parameters for listFolder


type alias ListFolderResponse =
{ entries : List Metadata
, cursor : String
, hasMore : Basics.Bool 
}

See https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder


type ListFolderError
    = PathListError LookupError
    | OtherListError String Json.Encode.Value
    | OtherListFailure Http.Error

See https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder


type ListFolderContinueError
    = PathListContinueError LookupError
    | ExpiredCursorError
    | OtherListContinueError String Json.Encode.Value
    | OtherListContinueFailure Http.Error

See https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue


type MediaInfo

Additional information if the file is a photo or video.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type MediaMetadata

Metadata for a photo or video.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias PhotoMetadata =
{ dimensions : Maybe Dimensions
, location : Maybe GpsCoordinates
, timeTaken : Maybe Time.Posix 
}

Metadata for a photo.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias VideoMetadata =
{ dimensions : Maybe Dimensions
, location : Maybe GpsCoordinates
, timeTaken : Maybe Time.Posix
, duration : Maybe Basics.Int 
}

Metadata for a video.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload

WARNING: elm-dropbox may give the incorrect values for duration, since Elm currently does not provide a way to parse and represent 64-bit integers.


type alias Dimensions =
{ height : Basics.Int
, width : Basics.Int 
}

Dimensions for a photo or video.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload

WARNING: elm-dropbox may give the incorrect values, since Elm currently does not provide a way to parse and represent 64-bit integers.


type alias GpsCoordinates =
{ latitude : Basics.Float
, longitude : Basics.Float 
}

The GPS coordinate of the photo/video.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias FileSharingInfo =
{ readOnly : Basics.Bool
, parentSharedFolderId : String
, modifiedBy : Maybe String 
}

Sharing info for a file which is contained by a shared folder.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload


type alias PropertyGroup =
{ templateId : String
, fields : Dict String String 
}

Collection of custom properties in filled property templates.

See https://www.dropbox.com/developers/documentation/http/documentation#files-upload