criske / koonsplash

Unofficial client side Kotlin wrapper for Unsplash API.

Koonsplash

Unofficial client side Kotlin wrapper for Unsplash API.

Usage

runBlocking {
    val api = Koonsplash.builder("my-access-key-client-id")
                .openLinksStrategy {
                    //if _openLinksStrategy_ is not set. Koonsplash will try to open browser 
                    //or photo links using os terminal.
                    Desptop.browse(it)
                    Result.success(Unit)
                }
                .build()
                .authenticated(
                    Koonsplash.AuthenticatedBuilder("secret-key".toCharArray())
                        .scopes(AuthScope.PUBLIC + AuthScope.READ_USER + AuthScope.WRITE_USER)
                )   
                .api
    val me = api.endpoint("/me").call()
    val myLikesLink: Link.Api = me["links"]["likes"]()
    val firstLikedPhoto = myLikesLink.call()[0]
    val link: Link.Download = firstLikedPhoto["links"]["download_location"]()
    val photo: Link.Browser = link.download(File("<path>"), id)
    // or with progress
    link
        .downloadWithProgress(File("<path>"), id)
        .collect { status ->
            when (status) {
                is ApiCall.Status.Canceled -> status.err.printStackTrace()
                is ApiCall.Status.Current  -> println("Progress: ${status.value}%")
                is ApiCall.Status.Done     -> status.resource.open()
                is ApiCall.Status.Starting -> println("Starting")
            }
        }
}        

DSL Support for image resizing

val photo: Link.Photo = firstLikedPhoto["urls"]["raw"]
val resizedPhoto = photo.resize{
    500u.w
    500u.h
    fit(Fit.CROP)
    crop(Crop.TOP, Crop.LEFT)
    100.q
    fm(Fm.PNG)
}.toDownloadLink()
val saved: Link.Browser = resizedPhoto.download(File("<path>"), "my-resized-photo")
saved.open()

Cancelling a request

val cancelButton = MutableSharedFlow<Unit>()
launch {
   val photo = api.call("/photos/random").cancelable(cancelFlow)
   if(photo != null){
     val link: Link.Download = photo["links"]["download_location"]()
     //...
   }else{
     //request was manually canceled
     showMessage("Canceled")
   }
}
launch {
   api.call("/photos/random")
        .cancelableExecute(cancelFlow)
        .collect{ status ->
            when (status) {
                is ApiCall.Status.Starting -> showProgressBar()
                is ApiCall.Status.Current -> updateProgressBar(status.value)
                is ApiCall.Status.Done -> {
                    hideProgressBar()
                    val photo = status.resource()
                    //....
                }
                is ApiCall.Status.Canceled -> {
                    hideProgressBar()
                    showMessage("Canceled")
                }           
            }
        }
}
//pressing the supposed button will cancel the request.
launch {
    delay(1000)
    cancelButton.emit(Unit)
}

Work in progress...

koonsplash's Issues

Provide implementation AuthCalls

Control the login step from Authorizer.

When user introduces wrong credentials, it should allow to reintroduce credentials (show again a login "form").

Add logging

https://github.com/MicroUtils/kotlin-logging ?

then create logs in code where needed

Test AuthCallsImpl with mockwebserver

https://github.com/square/okhttp/tree/master/mockwebserver

Gather all auth custom exceptions and typedefs into a single file.

Gather all scathered auth custom exceptions and typedefs into a single file.

Create a custom exception for Api call result.

Something like ApiCallException(message, resultcode)

Make Koonsplash/KoonsplashAuth singleton.

After init / auth, clients should be able to call Koonsplash/KoonsplashAuth from anywhere using this extension Koonsplash.instance. This extension will return Koonsplash or KoonsplashAuth depending on context.

Unit test Authorizer Authorize confirm form use case.

We need to test Authorizer use case when after a successful login, an authorize confirmation form might be needed to submit in order to obtain the authorization code.

All api calls should be done in background by default.

It assumes that for example apu.raw()() is running on IO CoroutineDisptacher, no need for client to explicit launch a coroutine with IO dispatcher.

Might let client customize it by passing their own Dispatcher for api calls in Koonsplash builder.

AuthCodeServerImpl#stop() should catch IOException

AuthCodeServerImpl#start() should catch IOException and return false.
Also if the server not started in the timeout limit should call stop() and return false.

Link entity for ApiJson.

Any url string values from ApiJson should be converted to a Link object.
There would these types of links:

• JsonLink (if link points to api resource). Json link should use the api.call("url")
• PhotoLink (if link points to a photo). Photo links can be "opened" or "downloaded"
• BrowserLink (if link can be opened in a browser).

Abstraction for api call result.

Right now the api call result is just json as string.
Client should be able to traverse this json and also should be able find links from json. This links can be opened or downloaded if the case,

Refactor Authorizer to implement an interface

Make AuthCodeServer to start at a specific port in Authorizer#authorize.

We need to pass the port to Authorizer#authorize
Thus, Passing an abstract factory for server to Authorizer constructor will solve this.

fun authorize(..., int port){
   val server = factory.get(host, port)
   server.start()
   ...
}

OAuth2 scopes should be passed to `Authorizer#authorize` as params.

This means Koonsplash#authenticated must have them as param as well.
Default is PUBLIC

Edit: [bug] passing other scope might throw expection

Write integration tests for Link types

Tests for Link.Download are mostly done. Need to test errors there.

LoginFormListener#listener should pass a Throwable

Abstract ApiCall#execute transformer.

It should not be tight coupled with OkHttp Response.

Use Uri for Link instead of plain string.

Implement Authorization Code Redirect Server

Create a proof of concept for AOuth2 loging in

Create AccessContext.

This context should encapsultate the access key and the auth token, because these two are used across the lib.
authToken must check on call if client is signed out (returning null will be suffice).

Install JaCoCo plugin for test code coverage.

also add it to ci as task

Implement ApiJsonResponse.Meta

this should contain info about rate limit and pagination (if that's the case)

Achieve 80% test coverage

Create a Converter.Factory for Gson

instead of passing the json client along with http client, let http client convert json responses to data classes

wainting for #25

Create a raw api call feature available for 0.1 release

Design thought:

launch {
 val api  = Koonsplash.build()...api
 val randomPhoto = api.raw("/photos/random")()
 val preparedPhoto = api.raw("/photos/{id}")
 val photo1 = preparedPhoto ("id1")
 val photo2 = preparedPhoto ("id2")
// assuming api is authenticated
 api.raw("/me", verb = PUT("username" to "john_doe"))()
}

Replace Moshi with Gson

Moshi doesn't support "snake case" to "camel case" field equivalation.

Test KoonsplashImpl authenticated

waiting for #34
waiting for #36

Auth Exception are too opaque - they should carry the cause of their failing.

Authorizer and AuthCalls should use coroutines.

Due to the fact the AuthorizerImpl logic is getting to hard to follow.

Remove Progress.ByStep

Clients can make their own ByStep by using Progress.Raw

Refactor Authorizer#authorize

move login submitter into its own class for starter.

Okhttp extend newCall to be a coroutine

Write tests for OAuth2 Authorizer flow.

Authrorizer should be injected in KoonsplashImpl

Api + ApiAuth should be injected into Koonsplash/Auth-Impl

Fix the spammy ApiCall.ProgressStatus.Current as percent

Should output unique int values from 0 to 100

Do not allow KoonsplahAuthImpl to do api calls after `signOut`.

Use case:

val koonsplash = ....
val api = koonsplash.api
koonsplash.signOut()
api.me() // this call should throw an error now

AuthTokenStorage implement and test

Part of Unsplash OAuth2 authentification

Create loader for API sensitive info like client id and secret key

Renaming stuff.

Rename

• ApiCall.ProgressStatus to ApiCall.Status

Create a concrete builder for Koonsplash interface

this way KoonsplashImpl is not exposed

Test KoonsplashImpl

Abstract authentification OAuth2 calls

Move storage from Authorizer to KoonsplashAuthImpl

Let KoonsplashAuthImpl to have the responsability to load and save Authtoken

Integrate test coverage with CI

Start first draft for authenticated Koonsplash

The root class will be Koonsplash that has the api keys.
Koonsplash#authenticated supendable will return AuthKoonsplash. Internally this method will use Authorizer#authorize for OAuth2 flow and get the AuthToken.

AuthKoonsplash then should have methods.

• signOut
• api (api should access all methods that require AuthToken, access will be async using coroutines)

Make `AuthScope` composable.

Also add AuthScope.ALL for all scopes.
AuthScope should support adding and subtraction.
So instead of passing a list o auth scopes on auth, clients should pass a composition of scopes.
When adding it should ignore if the scope was already added.
When subtracting if scope was not presesnt then should ignore (subtraction usually should be applied on ALL)
Use cases:

• AuthScope.PUBLIC + AuthScope.READ_USER
• AuthScope.ALL
• AuthScope.ALL - AuthScope.READ_USER (excludes read_user scope from all)

Make Link.Download#download extension for "single"

Convert Link.Download#download flow to "single" via extension. (meaning that progress status will be ignored)