view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# Apertur::SDK

Official Perl SDK for the [Apertur](https://apertur.ca) API. Supports API key and OAuth token authentication, session management, image uploads (plain and encrypted), long polling, webhook verification, and full resource CRUD.

## Installation

Requires Perl 5.26+ and is installed via standard CPAN tooling.

```bash
cpanm Apertur::SDK
```

Or from source:

```bash
perl Makefile.PL
make
make test
make install
```

## Quick Start

Create a client, open an upload session, and upload an image in a few lines. See the [API documentation](https://docs.apertur.ca) for a full overview.

```perl
use Apertur::SDK;

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

my $session = $client->sessions->create(label => 'My shoot');
my $image   = $client->upload->image($session->{uuid}, '/path/to/photo.jpg');

print "Uploaded: $image->{id}\n";
```

## Authentication

The client accepts either a long-lived API key or a short-lived OAuth bearer token. Only one is required. See [Authentication documentation](https://docs.apertur.ca/authentication).

```perl
use Apertur::SDK;

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

# OAuth token (e.g. obtained via your auth server)
my $client = Apertur::SDK->new(oauth_token => $access_token);

# Custom base URL (sandbox)
my $client = Apertur::SDK->new(
    api_key  => 'aptr_live_...',
    base_url => 'https://sandbox.api.aptr.ca',
);
```

Keys prefixed with `aptr_test_` automatically target the sandbox environment.

## Sessions

Upload sessions scope every image upload. You can create a session with optional settings, retrieve it, protect it with a password, and check delivery status. See [Sessions documentation](https://docs.apertur.ca/upload-sessions).

```perl
use Apertur::SDK;

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

# Create a session
my $session = $client->sessions->create(
    label     => 'Wedding reception',
    password  => 's3cr3t',
    maxImages => 200,
);

# Retrieve session details
my $details = $client->sessions->get($session->{uuid});

# Verify a password-protected session before uploading
my $result = $client->sessions->verify_password($session->{uuid}, 's3cr3t');

# Check per-destination delivery status. Returns:
#   { status => 'pending|active|completed|expired',
#     files => [...], lastChanged => '<ISO 8601>' }
my $status = $client->sessions->delivery_status($session->{uuid});

# Long-poll: server holds the response up to 5 min until something changes.
# Passing poll_from automatically widens the per-request timeout to 360 s.
$status = $client->sessions->delivery_status(
    $session->{uuid},
    poll_from => $status->{lastChanged},
);
```

## Uploading Images

Upload a plain image using a file path or a scalar reference with raw bytes. For end-to-end encrypted uploads, use `image_encrypted` with the server's RSA public key. See [Upload documentation](https://docs.apertur.ca/upload-sessions).

```perl
use Apertur::SDK;

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

# Upload from a file path
my $image = $client->upload->image($uuid, '/tmp/photo.jpg',
    filename => 'photo.jpg',
    mimeType => 'image/jpeg',
    source   => 'my-app',
);

# Upload from raw bytes
my $bytes = read_file_bytes('/tmp/photo.jpg');
my $image = $client->upload->image($uuid, \$bytes);

# Upload to a password-protected session
my $image = $client->upload->image($uuid, '/tmp/photo.jpg',
    password => 's3cr3t',
);

# Encrypted upload
my $server_key = $client->encryption->get_server_key();
my $image = $client->upload->image_encrypted(
    $uuid, '/tmp/photo.jpg', $server_key->{publicKey},
    filename => 'photo.jpg',
    mimeType => 'image/jpeg',
);
```

## Long Polling

Poll a session for new images, download each one, and acknowledge receipt to advance the queue. The `poll_and_process` helper loops automatically and calls your handler for every image. See [Long Polling documentation](https://docs.apertur.ca/long-po...

```perl
use Apertur::SDK;

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

# Manual poll / download / ack cycle
my $result = $client->polling->list($uuid);
for my $image (@{ $result->{images} }) {
    my $data = $client->polling->download($uuid, $image->{id});
    open my $fh, '>:raw', "/tmp/$image->{id}.jpg" or die $!;
    print $fh $data;
    close $fh;
    $client->polling->ack($uuid, $image->{id});
}

# Automatic loop with 60-second timeout and 3-second interval
$client->polling->poll_and_process(
    $uuid,
    sub {
        my ($image, $data) = @_;
        open my $fh, '>:raw', "/tmp/$image->{id}.jpg" or die $!;
        print $fh $data;
        close $fh;
        print "Saved $image->{id}\n";
    },
    interval => 3,
    timeout  => 60,
);
```

## Receiving Webhooks

Apertur signs every webhook payload so you can verify it was not tampered with. Three verification methods are available. See [Webhooks documentation](https://docs.apertur.ca/webhooks).

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

# Image delivery webhook
my $valid = verify_webhook_signature($body, $signature, $secret);