/ 
Apertur-SDK-0.02
/ Apertur::SDK

NAME

Apertur::SDK - Official Perl SDK for the Apertur API

VERSION

Version 0.01

SYNOPSIS

use Apertur::SDK;

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

# Create an upload session
my $session = $client->sessions->create(label => 'My shoot');

# Upload an image
my $image = $client->upload->image($session->{uuid}, '/path/to/photo.jpg');
print "Uploaded: $image->{id}\n";

# Long polling
$client->polling->poll_and_process(
    $session->{uuid},
    sub {
        my ($image, $data) = @_;
        open my $fh, '>:raw', "/tmp/$image->{id}.jpg" or die $!;
        print $fh $data;
        close $fh;
    },
    interval => 3,
    timeout  => 60,
);

DESCRIPTION

Official Perl SDK for the Apertur API. Supports API key and OAuth token authentication, session management, image uploads (plain and encrypted), long polling, webhook signature verification, and full resource CRUD for destinations, API keys, webhooks, and encryption keys.

CONSTRUCTOR

new(%args)

Creates a new Apertur SDK client. At least one of api_key or 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 (live or test) is automatically detected from the API key prefix. Test keys (aptr_test_...) default to the sandbox URL https://sandbox.api.aptr.ca.

RESOURCE ACCESSORS

sessions - Apertur::SDK::Resource::Sessions
upload - Apertur::SDK::Resource::Upload
uploads - Apertur::SDK::Resource::Uploads
polling - Apertur::SDK::Resource::Polling
destinations - Apertur::SDK::Resource::Destinations
keys - Apertur::SDK::Resource::Keys
webhooks - Apertur::SDK::Resource::Webhooks
encryption - Apertur::SDK::Resource::Encryption
stats - Apertur::SDK::Resource::Stats

AUTHENTICATION

The client accepts either a long-lived API key or a short-lived OAuth bearer token. Keys prefixed with 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);

ERROR HANDLING

All API errors throw typed 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;
    }
}

WEBHOOK VERIFICATION

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

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

ENCRYPTION

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

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

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

DEPENDENCIES

LWP::UserAgent
JSON
HTTP::Request::Common
Digest::SHA
MIME::Base64

Optional (for encryption only):

Crypt::OpenSSL::RSA
CryptX

LICENSE

MIT License. See the LICENSE file for details.

SEE ALSO

https://apertur.ca, https://docs.apertur.ca