NAME

WebService::Shutterstock::Customer - Class allowing API operations in the context of a specific customer

VERSION

version 0.006

SYNOPSIS

        my $customer = $shutterstock->auth("my-user" => "my-password");

        # retrieve list of lightboxes
        my $lightboxes = $customer->ligthboxes;

        # retrieve a specific lightbox for this user
        my $lightbox = $customer->lightbox(123);

        my $subscriptions = $customer->subscriptions;
        my $enhanced_subscription = $customer->subscription(license => 'enhanced');

        my $download_history = $customer->downloads;

        # license an image (if you only have a single active subscription)
        my $licensed_image = $customer->license_image(
                image_id => 59915404,
                size     => 'huge'
        );

        # license an image (if you have more than one active subscription)
        my $licensed_image = $customer->license_image(
                image_id     => 59915404,
                size         => 'huge',
                subscription => { license => 'standard' }
        );

DESCRIPTION

This class provides access to API operations (download history, lightbox interaction, subscriptions, etc) that require an authenticated customer (via "auth" in WebService::Shutterstock).

METHODS

account_id

Retrieves the account ID for this account.

metadata_field_definitions

Retrieves the set of metadata fields for your account (if so configured by Shutterstock). Returns an ArrayRef of HashRefs (or undef if this feature doesn't apply to your account). When licensing an image you should provide the required metadata values using the name_api values specified for each metadata field returned by this method.

subscriptions

Returns an ArrayRef of WebService::Shutterstock::Subscription objects for this customer account.

subscription

Convenience wrapper around the find_subscriptions method that always returns the first match (useful when you're matching on a field that is unique like id or license).

        # find the (single) subscription providing an enhanced license
        my $media_digital_subscription = $customer->subscription(license => 'enhanced');

find_subscriptions

Retrieve a list of WebService::Shutterstock::Subscription objects, based on the criteria passed in to the method. Filter criteria should have WebService::Shutterstock::Subscription attribute names as keys with the value to be matched as the value. Subscriptions that match ALL the provided criteria are returned as a list. Some examples:

        # simple equality filters
        my @active_subscriptions = $customer->find_subscriptions( is_active => 1 );
        my @active_subscriptions = $customer->find_subscriptions( is_active => 1 );

        # regular expressions work too
        my @all_media_subscriptions = $customer->find_subscriptions( license => qr{^media} );

        # use an anonymous sub for more detailed filters (i.e. subscriptions expiring in the 
        my @soon_to_expire = $customer->find_subscriptions(
                is_active            => 1,
                unix_expiration_time => sub { shift < time + ( 60 * 60 * 24 * 30 ) }
        );

lightboxes($get_extended_info)

Returns an ArrayRef of WebService::Shutterstock::Lightbox objects for this customer acount. By default, it gets only the lightbox information and the list of image IDs in the lightbox. If you would like to retrieve more details about those images (specifically sizes and thumbnail URLs) in a single HTTP request, just pass a true value as the only argument to this method.

lightbox($id)

Returns a specific lightbox (as a WebService::Shutterstock::Lightbox object) for the given $id (it must belong to this user). If that lightbox doesn't exist, undef will be returned. Unfortunately, Shutterstock's API currently returns an HTTP status of 500 on an unknown lightbox ID (which could mask other error situations).

downloads

Retrieve the download history for this customer account. You can specify a page_number argument if you prefer to retrieve a single page of results (starting with page 0).

The data returned will be a HashRef keyed by the subscription ID used to download the images and will look something like this:

        { "123456" =>            # subscription ID
                [
                        {
                                image_id => 1,
                                license  => 'standard',
                                time     => '2012-11-01 14:16:08',
                        },
                        {
                                image_id => 2,
                                license  => 'premier',
                                metadata => { purchase_order => 'XYZ', client => 'My Client' },
                                time     => '2012-11-01 14:18:39',
                        },
                        # etc...
                ]
        }

You can fetch the redownloadable_state of a particular image (image_id must also be specified):

        my $redownloadable_state = $customer->downloads(
                image_id => 11024440,
                field    => "redownloadable_state"
        );

In this call, you should see an extra field inside the image block indicating whether the image qualifies as a redownload under that subscription:

        { "123456" =>            # subscription ID
                [
                        {
                                image_id => 1,
                                license  => 'standard',
                                time     => '2012-11-01 14:16:08',
                                redownloadable_state => 1          # boolean
                        }
                ]
        }

license_image(image_id => $image_id, size => $size)

Licenses a specific image in the requested size. Returns a WebService::Shutterstock::LicensedImage object.

If you have more than one active subscription, you will need to specify which subscription you would like to use for licensing with a subscription argument. You can pass in a WebService::Shutterstock::Subscription object or any criteria that can be passed to "find_subscriptions" that will identify a single subscription. For instance:

        # by "license"
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => { license => 'standard' }
        );

        # by "id"
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => { id => 63746273 }
        );

        # or explicitly, with a subscription object
        my $enhanced = $customer->subscription( license => 'enhanced' );
        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => $enhanced
        );

If your account is configured by Shutterstock to require custom metadata values to be provided when licensing images (see "metadata_field_definitions"), you can provide those values using the metadata parameter. For instance:

        my $licensed_image = $customer->license_image(
                image_id     => $image_id,
                size         => $size,
                subscription => $subscription,
                metadata     => { purchase_order => '<value here>', }
        );

If the image requires an acknowledgment that it will only be used in an editorial context, you must pass the editorial_acknowledgement => 1 argument to the method.

AUTHOR

Brian Phillips <bphillips@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Brian Phillips and Shutterstock, Inc. (http://shutterstock.com).

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm WebService::Shutterstock

perl -MCPAN -e shell
install WebService::Shutterstock