| 1 | # -*- perl -*- | ||
| 2 | |||
| 3 | # Copyright (c) 2019 | ||
| 4 | # Author: Jeff Weisberg | ||
| 5 | # Created: 2019-Jul-22 16:07 (EDT) | ||
| 6 | # Function: Deduce Ingest API | ||
| 7 | |||
| 8 | package WWW::Deduce::Ingest; | ||
| 9 | use JSON; | ||
| 10 | use LWP::UserAgent; | ||
| 11 | use LWP::Protocol::https; | ||
| 12 | use HTTP::Request; | ||
| 13 | use Digest::SHA 'sha1_hex', 'sha256_hex'; | ||
| 14 | use Digest::MD5 'md5_hex'; | ||
| 15 | |||
| 16 | use strict; | ||
| 17 | |||
| 18 | our $VERSION = '1.1'; | ||
| 19 | |||
| 20 | my $COLLECT_URL = '//lore.deduce.com/p/collect'; | ||
| 21 | my $EVENT_URL = 'https://event.deduce.com/p/event'; # always https | ||
| 22 | my $VERHASH = substr(sha1_hex("perl/$VERSION"), 0, 16); | ||
| 23 | my $TIMEOUT = 2; | ||
| 24 | |||
| 25 | my $limit; | ||
| 26 | my $lastt; | ||
| 27 | |||
| 28 | |||
| 29 | sub new { | ||
| 30 | my $class = shift; | ||
| 31 | my $site = shift; | ||
| 32 | my $apikey = shift; | ||
| 33 | my $opts = shift || {}; | ||
| 34 | |||
| 35 | return bless { | ||
| 36 | site => $site, | ||
| 37 | apikey => $apikey, | ||
| 38 | collect_url => $COLLECT_URL, | ||
| 39 | event_url => $EVENT_URL, | ||
| 40 | %$opts, | ||
| 41 | }, $class; | ||
| 42 | } | ||
| 43 | |||
| 44 | sub html { | ||
| 45 | my $me = shift; | ||
| 46 | my $email = shift; | ||
| 47 | my $opts = shift; | ||
| 48 | |||
| 49 | my $data = { site => $me->{site}, vers => $VERHASH }; | ||
| 50 | $data->{testmode} = JSON::true if $opts->{testmode} || $me->{testmode}; | ||
| 51 | |||
| 52 | if( email_valid($email) ){ | ||
| 53 | $email = trim_space($email); | ||
| 54 | |||
| 55 | $data->{ehlm5} = md5_hex(lc $email); | ||
| 56 | $data->{ehum5} = md5_hex(uc $email); | ||
| 57 | $data->{ehls1} = sha1_hex(lc $email); | ||
| 58 | $data->{ehus1} = sha1_hex(uc $email); | ||
| 59 | $data->{ehls2} = sha256_hex(lc $email); | ||
| 60 | $data->{ehus2} = sha256_hex(uc $email); | ||
| 61 | } | ||
| 62 | |||
| 63 | my $url = $opts->{url}; | ||
| 64 | unless( $url ){ | ||
| 65 | if( $opts->{use_ssl} ){ | ||
| 66 | $url = 'https:' . $me->{collect_url}; | ||
| 67 | }elsif( exists $opts->{use_ssl} ){ | ||
| 68 | $url = 'http:' . $me->{collect_url}; | ||
| 69 | }else{ | ||
| 70 | $url = $me->{collect_url}; | ||
| 71 | } | ||
| 72 | } | ||
| 73 | |||
| 74 | my $json = to_json($data, {utf8 => 1, pretty => 1}); | ||
| 75 | |||
| 76 | my $html = <<EOS; | ||
| 77 | <script type="text/javascript"> | ||
| 78 | var dd_info = $json | ||
| 79 | </script> | ||
| 80 | <script type="text/javascript" src="$url" async></script> | ||
| 81 | EOS | ||
| 82 | ; | ||
| 83 | |||
| 84 | return $html; | ||
| 85 | |||
| 86 | } | ||
| 87 | |||
| 88 | |||
| 89 | # return undef on success, else an error message | ||
| 90 | |||
| 91 | sub events { | ||
| 92 | my $me = shift; | ||
| 93 | my $evts = shift; | ||
| 94 | my $opts = shift; | ||
| 95 | |||
| 96 | return if limited(); | ||
| 97 | |||
| 98 | my $site = $me->{site}; | ||
| 99 | my $apikey = $me->{apikey}; | ||
| 100 | my $url = $opts->{url} || $me->{event_url}; | ||
| 101 | my $timeout = $opts->{timeout} || ($TIMEOUT + @$evts/10); | ||
| 102 | |||
| 103 | my $post = { site => $site, apikey => $apikey, vers => $VERHASH }; | ||
| 104 | $post->{backfill} = JSON::true if $opts->{backfill}; | ||
| 105 | $post->{testmode} = JSON::true if $opts->{testmode} || $me->{testmode}; | ||
| 106 | $post->{events} = [ map { fixup_evt($_) } @$evts ]; | ||
| 107 | |||
| 108 | # print STDERR to_json($post); | ||
| 109 | |||
| 110 | # https post | ||
| 111 | my $req = HTTP::Request->new(POST => $url); | ||
| 112 | $req->content_type('application/json'); | ||
| 113 | $req->content( to_json($post) ); | ||
| 114 | |||
| 115 | my $ua = LWP::UserAgent->new(timeout => $timeout); | ||
| 116 | my $res = $ua->request($req); | ||
| 117 | |||
| 118 | if( $res->code() == 200 ){ | ||
| 119 | adjust_ok(); | ||
| 120 | return ; | ||
| 121 | } | ||
| 122 | |||
| 123 | adjust_fail(); | ||
| 124 | return $res->code() . " " . $res->content(); | ||
| 125 | } | ||
| 126 | |||
| 127 | sub event { | ||
| 128 | my $me = shift; | ||
| 129 | my $email = shift; | ||
| 130 | my $ip = shift; | ||
| 131 | my $event = shift; | ||
| 132 | my $additional = shift; | ||
| 133 | my $opts = shift; | ||
| 134 | |||
| 135 | return "invalid email" unless email_valid($email); | ||
| 136 | |||
| 137 | my %event; | ||
| 138 | %event = %$additional if $additional; | ||
| 139 | $event{email} = $email; | ||
| 140 | $event{ip} = $ip; | ||
| 141 | $event{event} = $event; | ||
| 142 | |||
| 143 | $me->events( [\%event], $opts); | ||
| 144 | } | ||
| 145 | |||
| 146 | # hash + delete plaintext email, email_prev, cc | ||
| 147 | sub fixup_evt { | ||
| 148 | my $e = shift; | ||
| 149 | |||
| 150 | my %e = %$e; | ||
| 151 | my $email = $e{email}; | ||
| 152 | |||
| 153 | if( email_valid($email) ){ | ||
| 154 | $email = lc trim_space($email); | ||
| 155 | $e{ehls1} = sha1_hex($email); | ||
| 156 | delete $e{email}; | ||
| 157 | |||
| 158 | unless( exists $e{email_provider} ){ | ||
| 159 | $e{email_provider} = (split /\@/, $email)[1]; | ||
| 160 | } | ||
| 161 | } | ||
| 162 | |||
| 163 | if( email_valid($e{email_prev}) ){ | ||
| 164 | $e{ehls1_prev} = sha1_hex(lc trim_space($e{email_prev})); | ||
| 165 | delete $e{email_prev}; | ||
| 166 | } | ||
| 167 | |||
| 168 | if( $e{cc} ){ | ||
| 169 | my $cc = $e{cc}; | ||
| 170 | $cc =~ s/[^0-9]//; | ||
| 171 | $e{ccs1} = sha1_hex($cc); | ||
| 172 | delete $e{cc}; | ||
| 173 | } | ||
| 174 | |||
| 175 | return \%e; | ||
| 176 | } | ||
| 177 | |||
| 178 | sub trim_space { | ||
| 179 | my $s = shift; | ||
| 180 | |||
| 181 | $s =~ s/^\s+//; | ||
| 182 | $s =~ s/\s+$//; | ||
| 183 | return $s; | ||
| 184 | } | ||
| 185 | |||
| 186 | sub email_valid { | ||
| 187 | my $e = shift; | ||
| 188 | |||
| 189 | return $e =~ /.+\@.+\..+/; | ||
| 190 | } | ||
| 191 | |||
| 192 | # rate limit events if they are failing | ||
| 193 | sub limited { | ||
| 194 | |||
| 195 | my $t = time(); | ||
| 196 | $limit ||= 0; | ||
| 197 | $lastt ||= $t; | ||
| 198 | my $dt = $t - $lastt; | ||
| 199 | $lastt = $t; | ||
| 200 | |||
| 201 | $limit *= 0.999 ** $dt; | ||
| 202 | |||
| 203 | return rand(100) < $limit; | ||
| 204 | } | ||
| 205 | sub adjust_ok { | ||
| 206 | $limit -= 5; | ||
| 207 | $limit = 0 if $limit < 0; | ||
| 208 | } | ||
| 209 | sub adjust_fail { | ||
| 210 | $limit = (9 * $limit + 100) / 10; | ||
| 211 | $limit = 100 if $limit > 100; | ||
| 212 | } | ||
| 213 | |||
| 214 | =head1 NAME | ||
| 215 | |||
| 216 | WWW::Deduce::Ingest - an interface to Deduce Ingestion | ||
| 217 | |||
| 218 | =head1 SYNOPSIS | ||
| 219 | |||
| 220 | use WWW:Deduce::Ingest; | ||
| 221 | |||
| 222 | my $d = WWW::Deduce::Ingest->new( 'my site id', 'my secret api key' ); | ||
| 223 | |||
| 224 | # output html widget | ||
| 225 | print $d->html('email@example.com'); | ||
| 226 | |||
| 227 | # send an event | ||
| 228 | my $err = $d->event( 'email@example.com', '192.0.2.3', 'eventname', { ... }, $opts ); | ||
| 229 | print STDERR "uh oh! $err\n" if $err; | ||
| 230 | |||
| 231 | |||
| 232 | =head1 INTERFACE | ||
| 233 | |||
| 234 | =head2 new( site, apikey ) | ||
| 235 | |||
| 236 | Create a new object. You need to pass in the site id and api key | ||
| 237 | that were assigned to you by Deduce. | ||
| 238 | |||
| 239 | =head2 html( email, opts ) | ||
| 240 | |||
| 241 | Generate HTML to place on your web page. | ||
| 242 | |||
| 243 | =over | ||
| 244 | |||
| 245 | =item C<email> | ||
| 246 | |||
| 247 | The user's email address. | ||
| 248 | It will be processed and hashed, not used directly. | ||
| 249 | |||
| 250 | =back | ||
| 251 | |||
| 252 | |||
| 253 | =head2 event(email, client_ip, eventtype, additional, opts) | ||
| 254 | |||
| 255 | When something interesting happens on your site, tell Deduce. | ||
| 256 | |||
| 257 | =over | ||
| 258 | |||
| 259 | =item C<email> | ||
| 260 | |||
| 261 | The user's email address. | ||
| 262 | It will be processed and hashed, not used directly. | ||
| 263 | |||
| 264 | |||
| 265 | =item C<client_ip> | ||
| 266 | |||
| 267 | the user's IP address in dotted quad format (IPv4), or coloned octopus (IPv6). | ||
| 268 | can often be found in $ENV{REMOTE_ADDR}. | ||
| 269 | |||
| 270 | =item C<eventtype> | ||
| 271 | |||
| 272 | the event type. | ||
| 273 | Consult with Deduce support to determine the event types. | ||
| 274 | |||
| 275 | =item C<additional> | ||
| 276 | |||
| 277 | a hashref of event data to send. | ||
| 278 | Consult with Deduce support to determine data to send. | ||
| 279 | |||
| 280 | if you pass in 'email_prev' or 'cc' fields, they will be automatically | ||
| 281 | processed and hashed, not send directly. | ||
| 282 | |||
| 283 | =item C<returns> | ||
| 284 | |||
| 285 | if there is an error, the error message will be returned. | ||
| 286 | on success, nothing. | ||
| 287 | |||
| 288 | =back | ||
| 289 | |||
| 290 | =head2 events(evts, opts) | ||
| 291 | |||
| 292 | You can send several related events, by sending an array of event data. | ||
| 293 | |||
| 294 | =over | ||
| 295 | |||
| 296 | =item C<evts> | ||
| 297 | |||
| 298 | an array of event data (hashrefs). | ||
| 299 | |||
| 300 | the events must contain valid email, ip, and event fields. | ||
| 301 | |||
| 302 | any email, email_prev, and cc fields will automatically be processed and hashed. | ||
| 303 | |||
| 304 | =item C<returns> | ||
| 305 | |||
| 306 | if there is an error, the error message will be returned. | ||
| 307 | on success, nothing. | ||
| 308 | |||
| 309 | =back | ||
| 310 | |||
| 311 | =head1 BUGS | ||
| 312 | |||
| 313 | There are no known bugs in the module. | ||
| 314 | |||
| 315 | =head1 SEE ALSO | ||
| 316 | |||
| 317 | http://www.deduce.com/ | ||
| 318 | |||
| 319 | =head1 LICENSE | ||
| 320 | |||
| 321 | This software may be copied and distributed under the terms | ||
| 322 | found in the Perl "Artistic License". | ||
| 323 | |||
| 324 | A copy of the "Artistic License" may be found in the standard | ||
| 325 | Perl distribution. | ||
| 326 | |||
| 327 | =cut | ||
| 328 | |||
| 329 | 1; |