view release on metacpan or  search on metacpan

lib/WWW/Kickstarter.pm  view on Meta::CPAN

      'goal',               # 'all' (default), '0':<=$1k, '1':$1k to $10k, '2':$10k to $100k, '3':$100k to $1M, '4':>$1M
      'raised',             # 'all' (default), '0':<75%, '1':75% to 100%, '2':>100%
      'sort',               # 'magic' (default), 'end_date', 'newest', 'launch_date', 'popularity', 'most_funded'
   ) {
      $form{$field_name} = exists($fixed->{$field_name}) ? $fixed->{$field_name} : delete($opts{$field_name});
   }

   $form{q}        = ''      if !defined($form{q});
   $form{category} = ''      if !defined($form{category});
   $form{tag}      = ''      if !defined($form{tag});
   $form{location} = ''      if !defined($form{location});
   $form{state}    = 'all'   if !defined($form{state})       || !length($form{state});
   $form{pledged}  = 'all'   if !defined($form{pledged})     || !length($form{pledged});
   $form{goal}     = 'all'   if !defined($form{goal})        || !length($form{goal});
   $form{raised}   = 'all'   if !defined($form{raised})      || !length($form{raised});
   $form{sort}     = 'magic' if !defined($form{sort})        || !length($form{sort});

   $form{state} =~ /^(?:all|live|successful)\z/
      or my_croak(400, "Unrecognized value for state. Valid: all, live, successful");
   $form{pledged} =~ /^(?:all|[01234])\z/
      or my_croak(400, "Unrecognized value for pledged. Valid: all, 0, 1, 2, 3, 4");
   $form{goal} =~ /^(?:all|[01234])\z/
      or my_croak(400, "Unrecognized value for goal. Valid: all, 0, 1, 2, 3, 4");
   $form{raised} =~ /^(?:all|[012])\z/
      or my_croak(400, "Unrecognized value for raised. Valid: all, 0, 1, 2");
   $form{sort} =~ /^(?:magic|end_date|newest|launch_date|popularity|most_funded)\z/
      or my_croak(400, "Unrecognized value for sort. Valid: magic, end_date, newest, launch_date, popularity, most_funded");

   my $url = URI->new('discover', 'http');
   $url->query_param_append( term        => $form{q}        ) if length($form{q});
   $url->query_param_append( category_id => $form{category} ) if length($form{category});
   $url->query_param_append( tag_id      => $form{tag}      ) if length($form{tag});
   $url->query_param_append( woe_id      => $form{location} ) if length($form{location});
   $url->query_param_append( backed      => '1'             ) if $form{backed_by_self};
   $url->query_param_append( starred     => '1'             ) if $form{starred_by_self};
   $url->query_param_append( social      => '1'             ) if $form{backed_by_friends};
   $url->query_param_append( staff_picks => '1'             ) if $form{picked_by_staff};
   $url->query_param_append( state       => $form{state}    ) if $form{state}   ne 'all';
   $url->query_param_append( pledged     => $form{pledged}  ) if $form{pledged} ne 'all';
   $url->query_param_append( goal        => $form{goal}     ) if $form{goal}    ne 'all';
   $url->query_param_append( raised      => $form{raised}   ) if $form{raised}  ne 'all';
   $url->query_param_append( sort        => $form{sort}     ) if $form{sort} ne 'magic';

   return $self->_call_api($url, [ 'iterator', cursor_style=>'page' ], 'Project', %opts);
}


# ---


sub myself {
   my $self = shift;
   return $self->_call_api('users/self', 'single', 'User::Myself', @_);
}

sub my_id {
   my ($self) = @_;
   return $self->{my_id};
}

sub my_notification_prefs {
   my $self = shift;
   return $self->_call_api('users/self/notifications', 'list', 'NotificationPref', @_);
}

sub my_projects_created {
   my $self = shift;
   return $self->_call_api('users/self/projects/created', 'list', 'Project', @_);
}

# There's no way to have 'discover?backed=1' return the results sorted by backing timestamp,
# so we'll continue to use the original interface ('users/self/projects/backed').
# But for consistency and possibly for foward-compatibility, we'll require a page-style cursor.
sub my_projects_backed {
   my ($self, %opts) = @_;

   if (exists($opts{start})) {
      my_croak(400, "Unrecognized parameter start");
   }

   if (defined(my $page = delete($opts{page}))) {
      $opts{start} = ($page - 1) * 10;
   }

   return $self->_call_api('users/self/projects/backed', [ 'iterator', cursor_style=>'start' ], 'Project', %opts);
}

# There's no way to have 'discover?starred=1' return the results sorted by starring timestamp,
# so we'll continue to use the original interface ('users/self/projects/starred').
# But for consistency and possibly for forward-compatibility, we'll require a page-style cursor.
sub my_projects_starred {
   my ($self, %opts) = @_;

   if (exists($opts{start})) {
      my_croak(400, "Unrecognized parameter start");
   }

   if (defined(my $page = delete($opts{page}))) {
      $opts{start} = ($page - 1) * 10;
   }

   return $self->_call_api('users/self/projects/starred', [ 'iterator', cursor_style=>'start' ], 'Project', %opts);
}

sub user {
   my_croak(400, "Incorrect usage") if @_ < 2;
   my $self    = shift;
   my $user_id = shift;  # From "id" field. Cannot be "slug".
   return $self->_call_api('users/'.uri_escape_utf8($user_id), [ 'single', recognize_404=>1 ], 'User', @_);
}

sub user_projects_created {
   my_croak(400, "Incorrect usage") if @_ < 2;
   my $self    = shift;
   my $user_id = shift;  # From "id" field. Cannot be "slug".
   return $self->_call_api('users/'.uri_escape_utf8($user_id).'/projects/created', [ 'list', recognize_404=>1 ], 'Project', @_);
}

sub project {
   my_croak(400, "Incorrect usage") if @_ < 2;
   my $self       = shift;

lib/WWW/Kickstarter.pm  view on Meta::CPAN

=item * C<< agent => "application_name/version " >>

The string to pass to Kickstarter in the User-Agent HTTP header.
If the string ends with a space, the name and version of this library will be appended,
as will the name of version of the underling HTTP client.


=item * C<< impolite => 1 >>

This module throttles the rate at which it sends requests to Kickstarter.
It won't place another request until C<$X> seconds has passed since the last request,
where C<$X> is the amount of time taken to fulfill the last request, but at most 4 seconds.

C<< impolite => 1 >> disables the throttling.


=item * C<< http_client_class => $class_name >>

The class to use instead of L<WWW::Kickstarter::HttpClient::Lwp> as the HTTP client.
For example, this would allow you to easily substitute L<Net::Curl> for L<LWP::UserAgent>.
See L<WWW::Kickstarter::HttpClient> for documentation on the interface the replacement class needs to provide.


=item * C<< json_parser_class => $class_name >>

The class to use instead of L<WWW::Kickstarter::JsonParser::JsonXs> as the JSON parser.
For example, this would allow you to easily substitute L<JSON::PP> for L<JSON::XS>.
See L<WWW::Kickstarter::JsonParser> for documentation on the interface the replacement class needs to provide.


=back


=head1 ACCESSORS

=head2 my_id

   my $user_id = $ks->my_id;

Returns the id of the logged-in user.


=head1 API CALLS

=head2 login

   my $myself = $ks->login($email, $password);

You must login using your standard Kickstarter credentials before you can query the API.

Returns a L<WWW::Kickstarter::Data::User::Myself> object for the user that logged in.


=head2 myself

   my $myself = $ks->myself();

Fetches and returns the logged-in user as a L<WWW::Kickstarter::Data::User::Myself> object.


=head2 my_notification_prefs

   my @notification_prefs = $ks->my_notification_prefs();

Fetches and returns the the logged-in user's notification preferences of backed projects as L<WWW::Kickstarter::Data::NotificationPref> objects.
The notification preferences for the project created last is returned first.


=head2 my_projects_created

   my @projects = $ks->my_projects_created();

Fetches and returns the projects created by the logged-in user as L<WWW::Kickstarter::Data::Project> objects.
The project created last is returned first.


=head2 my_projects_backed

   my $projects_iter = $ks->my_projects_backed(%opts);

Returns an L<iterator|WWW::Kickstarter::Iterator> that fetches and returns the projects backed by the logged-in user as L<WWW::Kickstarter::Data::Project> objects.
The most recently backed project is returned first.

Note that some projects may be returned twice. This happens when the data being queried changes while the results are being traversed.

Options:

=over

=item * C<< page => $page_num >>

If provided, the pages of results before the specified page number are skipped.

=back


=head2 my_projects_starred

   my $projects_iter = $ks->my_projects_starred(%opts);

Returns an L<iterator|WWW::Kickstarter::Iterator> that fetches and returns the projects starred by the logged-in user as L<WWW::Kickstarter::Data::Project> objects.
The most recently starred project is returned first.

Note that some projects may be returned twice. This happens when the data being queried changes while the results are being traversed.

Options:

=over

=item * C<< page => $page_num >>

If provided, the pages of results before the specified page number are skipped.

=back


=head2 user

   my $user = $ks->user($user_id);

Fetches and returns the specified user as a L<WWW::Kickstarter::Data::User> object.

Note that the argument must be the user's numerical id (as returned by L<C<< $user->id >>|WWW::Kickstarter::Data::User/id>).