view release on metacpan or  search on metacpan

lib/GitHub/Apps/Auth.pm  view on Meta::CPAN

use overload
    '""'   => sub { shift->{sub}->() . "" },
    "." => sub {
        my ($self, $other, $reverse) = @_;
        return $reverse ?
            _lazy { "$other" . "$self" } :
            _lazy { "$self" . "$other" };
    };

sub new {
    my ($class, $sub) = @_;
    return bless { sub => $sub }, $class;
}

1;
__END__

=encoding utf-8

=head1 NAME

GitHub::Apps::Auth - The fetcher that get a token for GitHub Apps

=head1 SYNOPSIS

    use GitHub::Apps::Auth;
    my $auth = GitHub::Apps::Auth->new(
        private_key     => "<filename>", # when read private key from file
        private_key     => \$pk,         # when read private key from variable
        app_id          => <app_id>,
        login           => <organization or user>
    );
    # This method returns the cached token inside an object.
    # However, refresh expired token automatically.
    my $token  = $auth->issued_token;

    # If you want to use with Pithub
    use Pithub;
    # GitHub::Apps::Auth object behaves like a string.
    # This object calls the `issued_token` method
    # each time it evaluates as a string.
    my $ph = Pithub->new(token => $auth, ...);

=head1 DESCRIPTION

GitHub::Apps::Auth is the fetcher for getting a GitHub token of GitHub Apps.

This module provides a way to get a token that need to be updated regularly for GitHub API.

=head1 CONSTRUCTOR

=head2 new

    my $auth = GitHub::Apps::Auth->new(
        private_key     => "<filename>",
        app_id          => <app_id>,
        installation_id => <installation_id>
    );

Constructs an instance of C<GitHub::Apps::Auth> from credentials.

=head3 parameters

=head4 private_key

B<Required: true>

This parameter is a private key of the GitHub Apps.

This must be a filename or string in the pem format. You can get a private key from Settings page of GitHub Apps. See L<Generating a private key|https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#generating-a-priv...

=head4 app_id

B<Required: true>

This parameter is the App ID of your GitHub Apps. Use the C<App ID> in the About section of your GitHub Apps page.

=head4 installation_id

B<Required: exclusive to> C<login>

A C<installation_id> is an identifier of installation Organizations or repositories in GitHub Apps. This value is can be obtained from a webhook that is fired during installation. Also can be obtained from webhook's C<Recent Deliveries> of GitHub app...

=head4 login

B<Required: exclusive to> C<installation_id>

C<login> is used for detecting installation_id. If not set C<installation_id> and set C<login>, search C<installation_id> from the list of installations.

=head1 METHODS

=head2 issued_token

    my $token  = $auth->issued_token;

C<issued_token> returns a API token in string. This token is cached while valid.

When calling this method with condition that expired token, this method refreshes a token automatically.

=head2 token

This method returns an API token. Unlike C<issued_token>, this method not refresh an expired token.

=head2 expires

This returns the token expiration date in the epoch.

=head1 OPERATOR OVERLOADS

C<GitHub::Apps::Auth> is overloaded so that C<issued_token> is called when evaluated as a string. So probably be usable in GitHub client that use raw string API token. Ex L<Pithub>.

=head1 SEE ALSO

L<Authenticating with GitHub Apps|https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps>

=head1 LICENSE

Copyright (C) mackee.

This library is free software; you can redistribute it and/or modify