view release on metacpan or  search on metacpan

lib/Apertur/SDK.pm  view on Meta::CPAN

=head1 CONSTRUCTOR

=over 4

=item B<new(%args)>

Creates a new Apertur SDK client. At least one of C<api_key> or
C<oauth_token> must be provided.

    my $client = Apertur::SDK->new(
        api_key  => 'aptr_live_...',   # or aptr_test_...
        base_url => 'https://...',     # optional, auto-detected
        env      => 'live',            # optional, auto-detected from key prefix
    );

The environment (C<live> or C<test>) is automatically detected from
the API key prefix. Test keys (C<aptr_test_...>) default to the
sandbox URL C<https://sandbox.api.aptr.ca>.

=back

=head1 RESOURCE ACCESSORS

=over 4

=item B<sessions> - L<Apertur::SDK::Resource::Sessions>

=item B<upload> - L<Apertur::SDK::Resource::Upload>

=item B<uploads> - L<Apertur::SDK::Resource::Uploads>

=item B<polling> - L<Apertur::SDK::Resource::Polling>

=item B<destinations> - L<Apertur::SDK::Resource::Destinations>

=item B<keys> - L<Apertur::SDK::Resource::Keys>

=item B<webhooks> - L<Apertur::SDK::Resource::Webhooks>

=item B<encryption> - L<Apertur::SDK::Resource::Encryption>

=item B<stats> - L<Apertur::SDK::Resource::Stats>

=back

=head1 AUTHENTICATION

The client accepts either a long-lived API key or a short-lived OAuth
bearer token. Keys prefixed with C<aptr_test_> automatically target the
sandbox environment.

    # API key
    my $client = Apertur::SDK->new(api_key => 'aptr_live_...');

    # OAuth token
    my $client = Apertur::SDK->new(oauth_token => $access_token);

=head1 ERROR HANDLING

All API errors throw typed L<Apertur::SDK::Error> objects:

    use Apertur::SDK;
    use Apertur::SDK::Error::Authentication;
    use Apertur::SDK::Error::NotFound;
    use Apertur::SDK::Error::RateLimit;
    use Apertur::SDK::Error::Validation;

    eval {
        my $session = $client->sessions->create(label => 'test');
    };
    if (my $err = $@) {
        if (ref $err && $err->isa('Apertur::SDK::Error::RateLimit')) {
            warn "Rate limited, retry after: " . ($err->retry_after // '?') . "s";
        }
        elsif (ref $err && $err->isa('Apertur::SDK::Error')) {
            warn "API error: " . $err->message;
        }
        else {
            die $err;
        }
    }

=head1 WEBHOOK VERIFICATION

    use Apertur::SDK::Signature qw(
        verify_webhook_signature
        verify_event_signature
        verify_svix_signature
    );

    my $valid = verify_webhook_signature($body, $signature, $secret);

=head1 ENCRYPTION

    use Apertur::SDK::Crypto qw(encrypt_image);

    my $result = encrypt_image($image_bytes, $pem_key);

Encryption requires optional dependencies C<Crypt::OpenSSL::RSA> and
C<CryptX>. These are loaded at runtime only when encryption functions
are called.

=head1 DEPENDENCIES

=over 4

=item L<LWP::UserAgent>

=item L<JSON>

=item L<HTTP::Request::Common>

=item L<Digest::SHA>

=item L<MIME::Base64>

=back

Optional (for encryption only):