wetransfer / wetransfer-swift-sdk Goto Github PK

View Code? Open in Web Editor NEW

39.0 5.0 7.0 1.63 MB

A Swift SDK for WeTransfer’s public API

License: MIT License

Ruby 5.73% Swift 93.82% Objective-C 0.45%

swift wetransfer sdk wt-branch-protection-default

wetransfer-swift-sdk's Introduction

This project is now archived as the Public WeTransfer API is no longer maintained.

WeTransfer-Swift-SDK

A Swift SDK for WeTransfer’s public API

For your API key and additional info please visit our developer portal.

Features
Requirements
Installation
Usage
Sample Application
Communication
License

Features

Create and upload a transfer from a single method call
Seperate methods for each seperate step in the process
Cancelling and resuming uploads

Requirements

iOS 9.0+ / macOS 10.10+
Xcode 9.4+
Swift 4.2+

Installation

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate WeTransfer into your Xcode project using Carthage, specify it in your Cartfile:

github "WeTransfer/WeTransfer-Swift-SDK" ~> 2.0

Run carthage update to build the framework and drag the built WeTransfer.framework into your Xcode project.

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding the WeTransfer SDK as a dependency is as easy as adding it to the dependencies value of your Package.swift.

Swift 4

dependencies: [
    .package(url: "https://github.com/Alamofire/WeTransfer-Swift-SDK.git", from: "2.0")
]

Note: Running swift test doesn’t work currently as Swift packages can’t have resources in their test targets.

Cocoapods

CocoaPods is a dependency manager for Cocoa projects.

To integrate the WeTransfer Swift SDK into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'WeTransfer-Swift-SDK', '>= 2.0'
end

Then, run the following command:

$ pod install

Usage

Before the SDK can do anything with the WeTransfer API, it needs to be authenticated with an API key. You can create an API key at the developer portal

Configure the client Create a configuration with your API key

let configuration = WeTransfer.Configuration(apiKey: "YOUR_API_KEY")
WeTransfer.configure(with: configuration)

Uploading files with a new transfer Creating a transfer and uploading files to it can be done with one method call, WeTransfer.uploadTransfer. Files in the SDK are represented by File objects, but this convenience methods expects an array of URLs pointing to files on your device. In the stateChanged closure you’re updated about things like the upload progress or whether is has completed or failed

let files = [...]
WeTransfer.uploadTransfer(saying: "Transfer Name", containing: files) { state in
    switch state {
    case .created(let transfer):
        print("Transfer created")
    case .uploading(let progress):
        print("Transfer uploading")
    case .completed(let transfer):
        print("Upload completed")
    case .failed(let error):
        XCTFail("Transfer failed: \(error.localizedDescription)")
    }
}

Sample Application

Included with the project is a neat little sample application that shows a possible use case for the SDK. It allows for photos and videos to be added to a transfer and shows the upload progress for the whole transfer, aAfter which the URL can be shared.

Communication

We recommend checking out the contribution guide for a full run-through of how to get started, but in short:

If you found a bug, open an issue.
If you have a feature request, open an issue.
If you want to contribute, submit a pull request.

License

The WeTransfer Swift SDK is available under the MIT license. See the LICENSE file for more info.

Code of Conduct

Everyone interacting in the WeTransfer Swift SDK project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct

wetransfer-swift-sdk's People

Contributors

Stargazers

Watchers

Forkers

cieslakdawid julianschiavo degtyarserg vikas100 hafizdean jebenjamin

wetransfer-swift-sdk's Issues

Cancel transfer in progress

Add a WeTransfer.cancel(_ transfer: Transfer) method to cancel the any operations regarding the provided transfer object

Add Contributing page

The project is still missing a CONTRIBUTING.md page, when added the README.md needs to reference it as well

Add property like isAdded to File and Transfer instead of checking identifier

Instead of checking for the availability of the identifier property, a dynamic property like isAdded should assume this behavior. Perhaps this could be handled in a protocol that handles this for File and Transfer (which both have the optional identifier property)

Handle unauthorized responses, retries and expired bearer in Authorizer

Currently the Authorizer class only stores a bearer and adds it to a given request. It should be responsible for the actual authentication and could also handle the case of unauthorized responses and when the sent bearer is expired.
The actual authentication part is currently done in the authorize() logic, which should be revised with most responsibility given to the Authorizer class

Support for URL items

The public API supports items that are only a URL. Currently the SDK treats items in a transfer only as a File. Files should be renamed to items at some places to allow for a more generic type

Fix unclear failure/success state of completing file upload

Right now in CompleteUploadOperation, in the success case of the complete upload request, the response is checked and still might fail based on the value of ok. The expected responses and HTTP status codes (which will trigger a fail when non 2xx) should be made clear with the API team

Update request responses to be more swifty

Using CodingKeys of Codable, properties like id should be renamed to identifier. All responses should also be renamed to their actual purpose, instead of directly conveying the API implementation details to the operations that handle them

Example project

Simple iOS application that creates a transfer from a file or photo picker

Carthage, Cocoapods and Package Manager support

Carthage already work, Cocaopods should be officially submitted and Swift Package should be investigated

Updated endpoints to contain both Parameters and Responses

Currently APIEndpoint structs contain generic references to the response that is expected to be returned from the request. The request parameters should be defined here as well

Support retrieve board call

Add support for https://wetransfer.github.io/wt-api-docs/index.html#retrieve-boards-information. Files in the retrieved board no longer have a local file URL, so this might be a challenge to do right

Transfer non-file transfer

Add the ability to create a transfer with in-memory objects like images. Any object that can be represented as Data should be able to be added to a transfer

Fix AsynchronousDependencyResultOperation with multiple dependencies

Currently AsynchronousDependencyResultOperation is used to handle the completion of all running instances of UploadFileOperation combined, but only the last result and error are used. This should be fixed by either allowing for all errors and results to be accessible or handling the UploadFileOperation dependencies better

Rethink failing upload without any files to upload

Right now UploadFilesOperation fails when there aren't any files to upload. This might be undesired as there is no actual failing happening when the transfer already has successfully uploaded files

Confusing logic of creating a transfer

Typically in implementer of this SDK creates a Transfer object locally, than calls a method that 'creates' it on the server in order to be able to add files to it. While the convenient uploadTransfer method handlers all of these operations, the more involved approach requires the user to manually create the transfer on the server.
This is an implementation detail (much like authorization) doesn't need to be exposed to the implementer.

Move URLSession uploading logic from UploadFilesOperation to APIClient

UploadFilesOperation should have little to do with creating a new URLSession and its delegate method. Ideally APIClient should have a method to create a new APIClient and accept a closure in which the delegate call can be passed through. These created URLSession instances and linked closures need to be removed when UploadFilesOperation finishes.

Support upload resuming

Currently the SDK doesn't persist any state so resuming uploads is not possible. It should be able to store information about uploaded chunks so transfer uploads could be resumed at any moment