driesvints / sponsors Goto Github PK

To speed things up we should fake the GraphQL requests. This will also be necessary to allow pull requests from GitHub since those won't be authenticated with a token and thus all PR's will fail.

We should also keep a portion of an integration test suite with a real token but those tests can be skipped if no token is set on the environment.

One of the bigger features I'd like to develop over time for this library is the ability to automatically grant and revoke perks. The way that this would work is that the library would offer a common interface for granting and revoking perks as well as an integration with either GitHub Webhooks or the Laravel Scheduler to check periodically for updates and then handle revoking or granting perks.

The actual implementations of whatever perk would be a custom implementation for the consumer of the library. This would open the door for an entire ecosystem of perks like a collection of integrations with different services and what not.

The interface would look as follows:

interface Perk
{
    public function grant(): bool;
    public function revoke(): bool;
    public function tiers(): array;
}

A practical example could be to grant access to a Discord server when you're sponsoring someone:

final class DiscordServerPerk implements Perk
{
    public function grant(): bool
    {
        // handle the logic to grant access to the server...
    }

    public function revoke(): bool
    {
        // handle the logic to revoke access to the server...
    }

    public function tiers(): array
    {
        // return the tiers that allow access to this perk...
    }
}

By returning the tiers that allow access to the perk the library should be able to automatically grant or revoke the perk depending when a user is changing tiers. If they're changing to a new tier that's also in the tiers list of the perk, nothing would change of course.

This idea is a little rough and there's probably tons of edge cases but it would be worth to explore a PoC for this.

Extend the API with even more useful methods:

// Check if driesvints has a sponsor listing...
$client->hasSponsorsListing('driesvints');

// Check if driesvints can sponsor nunomaduro...
$client->canSponsor('driesvints', 'nunomaduro');

// Check if driesvints is privately sponsored by nunomaduro...
$client->isPrivatelySponsoredBy('driesvints', 'nunomaduro');

With this library it should be possible to check if users are sponsoring through specific tiers. This will allow for even more fine-graned ACL capabilities and perk-granting.

The API would look as something like below. The used token is that of the "driesvints" GitHub account.

// Check if nunomaduro is sponsoring driesvints on the "$5 a month" tier:
$client->hasTier('nunomaduro', '$5 a month');

// Through the Sponsorable trait...
$user->hasTier('$5 a month');

// If the Sponsorable has its own token set and wants to check if they are sponsoring on a specific account:
$user->hasTierOn('$5 a month', 'nunomaduro');

These requests would always need to be made from the viewer's standpoint so the used token will need to be properly set. These API's probably need to be fleshed out some more.

GraphQL field of "tier":

tier {
    closestLesserValueTier {
        name
    }
    createdAt
    isCustomAmount
    isOneTime
    monthlyPriceInCents
    monthlyPriceInDollars
    name
    updatedAt
}

All tiers also have internal ID's on their node through their GraphQL field. But these aren't surfaced in the UI of GitHub Sponsors.

With a newly added createSponsorship mutation to the GitHub GraphQL API it should be possible to integrate this into the library.

// Make the current authenticated user sponsor the target account...
$client->sponsor('driesvints');

It's only possible of course to start sponsorships from the authenticated account. So implementations of the Sponsorable trait should have their own token set.

It would be cool if we could sync incoming GitHub webhooks into a database table so sponsorships can be checked against a persistent storage instead of performing GraphQL API calls.

We could leverage Spatie's https://github.com/spatie/laravel-github-webhooks package for this maybe.

This is atm a pretty vague idea as I'm not sure how practically this would be. Would we only sync sponsorships for the authed user on the client? Or more?

Also see https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#sponsorship

Ideally we'd build a dedicated documentation website with separate PHP-only and Laravel sections so it's more clear how to use the library in specific situations.

Leverage the newly added cancelSponsorship mutation: https://docs.github.com/en/graphql/reference/mutations#cancelsponsorship

Ideally we'd ship with a migration to add the github and github_token columns to the users table for Laravel.

Make use of the same way of ignoring migrations in Laravel first party packages if people don't want these to run automatically with the packge: https://laravel.com/docs/8.x/billing#database-migrations

Performing GraphQL calls can be costly and take quite a bit of time. Ideally I'd like to have dedicated caching support in the library. Most calls to check for sponsorships of GitHub users or to retrieve a list of sponsors don't need to be checked every second.

The way I see it we can ship a decorator for the GitHubSponsors client. This would look like as follows:

final class CachedGitHubSponsors
{
    public function __construct(
        private GitHubSponsors $client
    ) {}
    
    public function isSponsoredBy(string $account, string $sponsor, bool $isAccountAnOrganization = false): bool
    {
        // check cached status

        return $this->client->isSponsoredBy($account, $sponsor, $isAccountAnOrganization);
    }

    // ...
}

Maybe a common interface is needed?

I think this class should require a Psr\SimpleCache\CacheInterface implementation to handle the caching. For Laravel it can be retrieved from the already set cache store. We can add options to the github-sponsors.php config file to set the specific cache store and timeouts.

Retrieving a list of sponsorships should be a core feature of this library. With this, people can display the sponsorships on their app/website as well as do additional syncing in their app. The sponsorships on a GitHub account can be retrieved with the sponsorshipsAsMaintainer field. Ideally, you we'd hydrate a new GitHubSponsor object with the data from the GitHub account.

The api could like like this:

// Retrieve all sponsors of driesvints...
$sponsors = $client->sponsors('driesvints');

// With the Sponsorable trait...
$sponsors = $user->sponsors();

// Check if a user has sponsors...
$sponsors = $user->hasSponsors();

Which would return a lazy collection. I'd also opt to implement a cursor based paginator approach as well:

// Retrieve all sponsors of driesvints...
$sponsors = $client->paginateSponsors('driesvints');

Which would return an instance of Illuminate\Pagination\CursorPaginator. I'd also make use of BuildsWithQueries to resolve the cursor from the request for a Laravel implementation. See PaginationState.

Ideally we'd like to get rid of the organization methods so the user doesn't needs to know up front if they're checking a user or organization. An idea opted by @claudiodekker was to perform both the user and organization query with the username login and check which one would give the result:

query { 
  user(login: "driesvints") {
    viewerIsSponsoring
  },
  organization(login: "driesvints") {
    viewerIsSponsoring
  }
}

I think this would work. We'd have to rewrite some internals but then we could drop organization specific methods in the library.

For our Sponsorable trait we offer to set a GitHub username and token on the implementing class. But we don't actually check if the user or the token belong together. It would be good if we offered a way to users to do this or to either do this ourselves in the library before making API requests.

The way we could check this is to auth the client with the token and retrieve the user details, then check if the username is the same as the one set on the object.

It'd be cool if the library could track sponsored amounts of users. This could enable new ways to grant users perks based on how much someone has sponsored already.

Improve the API to work more like https://github.com/Astrotomic/laravel-github-sponsors

// Before...
$client->isSponsoredBy('driesvints', 'nunomaduro');
$client->isViewerSponsoring('driesvints');
$client->isViewerSponsoredBy('driesvints');

// After...
$client->login('driesvints')->isSponsoredBy('nunomaduro');
$client->viewer()->isSponsoring('driesvints');
$client->viewer()->isSponsoredBy('driesvints');