fs_selfservice/FS-SelfService/SelfService.pm

   1 package FS::SelfService;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT_OK $socket %autoload $tag);
   5 use Exporter;
   6 use Socket;
   7 use FileHandle;
   8 #use IO::Handle;
   9 use IO::Select;
  10 use Storable qw(nstore_fd fd_retrieve);
  11
  12 $VERSION = '0.03';
  13
  14 @ISA = qw( Exporter );
  15
  16 $socket =  "/usr/local/freeside/selfservice_socket";
  17 $socket .= '.'.$tag if defined $tag && length($tag);
  18
  19 #maybe should ask ClientAPI for this list
  20 %autoload = (
  21   'passwd'          => 'passwd/passwd',
  22   'chfn'            => 'passwd/passwd',
  23   'chsh'            => 'passwd/passwd',
  24   'login'           => 'MyAccount/login',
  25   'customer_info'   => 'MyAccount/customer_info',
  26   'edit_info'       => 'MyAccount/edit_info',
  27   'invoice'         => 'MyAccount/invoice',
  28   'cancel'          => 'MyAccount/cancel',
  29   'payment_info'    => 'MyAccount/payment_info',
  30   'process_payment' => 'MyAccount/process_payment',
  31   'list_pkgs'       => 'MyAccount/list_pkgs',
  32   'order_pkg'       => 'MyAccount/order_pkg',
  33   'cancel_pkg'      => 'MyAccount/cancel_pkg',
  34   'signup_info'     => 'Signup/signup_info',
  35   'new_customer'    => 'Signup/new_customer',
  36 );
  37 @EXPORT_OK = keys %autoload;
  38
  39 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
  40 $ENV{'SHELL'} = '/bin/sh';
  41 $ENV{'IFS'} = " \t\n";
  42 $ENV{'CDPATH'} = '';
  43 $ENV{'ENV'} = '';
  44 $ENV{'BASH_ENV'} = '';
  45
  46 my $freeside_uid = scalar(getpwnam('freeside'));
  47 die "not running as the freeside user\n" if $> != $freeside_uid;
  48
  49 foreach my $autoload ( keys %autoload ) {
  50
  51   my $eval =
  52   "sub $autoload { ". '
  53                    my $param;
  54                    if ( ref($_[0]) ) {
  55                      $param = shift;
  56                    } else {
  57                      $param = { @_ };
  58                    }
  59
  60                    $param->{_packet} = \''. $autoload{$autoload}. '\';
  61
  62                    simple_packet($param);
  63                  }';
  64
  65   eval $eval;
  66   die $@ if $@;
  67
  68 }
  69
  70 sub simple_packet {
  71   my $packet = shift;
  72   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
  73   connect(SOCK, sockaddr_un($socket)) or die "connect: $!";
  74   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
  75   SOCK->flush;
  76
  77   #shoudl trap: Magic number checking on storable file failed at blib/lib/Storable.pm (autosplit into blib/lib/auto/Storable/fd_retrieve.al) line 337, at /usr/local/share/perl/5.6.1/FS/SelfService.pm line 71
  78
  79   #block until there is a message on socket
  80 #  my $w = new IO::Select;
  81 #  $w->add(\*SOCK);
  82 #  my @wait = $w->can_read;
  83   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
  84   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
  85
  86   $return;
  87 }
  88
  89 =head1 NAME
  90
  91 FS::SelfService - Freeside self-service API
  92
  93 =head1 SYNOPSIS
  94
  95   # password and shell account changes
  96   use FS::SelfService qw(passwd chfn chsh);
  97
  98   # "my account" functionality
  99   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
 100
 101   my $rv = login( { 'username' => $username,
 102                     'domain'   => $domain,
 103                     'password' => $password,
 104                   }
 105                 );
 106
 107   if ( $rv->{'error'} ) {
 108     #handle login error...
 109   } else {
 110     #successful login
 111     my $session_id = $rv->{'session_id'};
 112   }
 113
 114   my $customer_info = customer_info( { 'session_id' => $session_id } );
 115
 116   #payment_info and process_payment are available in 1.5+ only
 117   my $payment_info = payment_info( { 'session_id' => $session_id } );
 118
 119   #!!! process_payment example
 120
 121   #!!! list_pkgs example
 122
 123   #!!! order_pkg example
 124
 125   #!!! cancel_pkg example
 126
 127   # signup functionality
 128   use FS::SelfService qw( signup_info new_customer );
 129
 130   my $signup_info = signup_info;
 131
 132   $rv = new_customer( {
 133                         'first'            => $first,
 134                         'last'             => $last,
 135                         'company'          => $company,
 136                         'address1'         => $address1,
 137                         'address2'         => $address2,
 138                         'city'             => $city,
 139                         'state'            => $state,
 140                         'zip'              => $zip,
 141                         'country'          => $country,
 142                         'daytime'          => $daytime,
 143                         'night'            => $night,
 144                         'fax'              => $fax,
 145                         'payby'            => $payby,
 146                         'payinfo'          => $payinfo,
 147                         'paycvv'           => $paycvv,
 148                         'paydate'          => $paydate,
 149                         'payname'          => $payname,
 150                         'invoicing_list'   => $invoicing_list,
 151                         'referral_custnum' => $referral_custnum,
 152                         'pkgpart'          => $pkgpart,
 153                         'username'         => $username,
 154                         '_password'        => $password,
 155                         'popnum'           => $popnum,
 156                         'agentnum'         => $agentnum,
 157                       }
 158                     );
 159
 160   my $error = $rv->{'error'};
 161   if ( $error eq '_decline' ) {
 162     print_decline();
 163   } elsif ( $error ) {
 164     reprint_signup();
 165   } else {
 166     print_success();
 167   }
 168
 169 =head1 DESCRIPTION
 170
 171 Use this API to implement your own client "self-service" module.
 172
 173 If you just want to customize the look of the existing "self-service" module,
 174 see XXXX instead.
 175
 176 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 177
 178 =over 4
 179
 180 =item passwd
 181
 182 =item chfn
 183
 184 =item chsh
 185
 186 =back
 187
 188 =head1 "MY ACCOUNT" FUNCTIONS
 189
 190 =over 4
 191
 192 =item login HASHREF
 193
 194 Creates a user session.  Takes a hash reference as parameter with the
 195 following keys:
 196
 197 =over 4
 198
 199 =item username
 200
 201 =item domain
 202
 203 =item password
 204
 205 =back
 206
 207 Returns a hash reference with the following keys:
 208
 209 =over 4
 210
 211 =item error
 212
 213 Empty on success, or an error message on errors.
 214
 215 =item session_id
 216
 217 Session identifier for successful logins
 218
 219 =back
 220
 221 =item customer_info HASHREF
 222
 223 Returns general customer information.
 224
 225 Takes a hash reference as parameter with a single key: B<session_id>
 226
 227 Returns a hash reference with the following keys:
 228
 229 =over 4
 230
 231 =item name
 232
 233 Customer name
 234
 235 =item balance
 236
 237 Balance owed
 238
 239 =item open
 240
 241 Array reference of hash references of open inoices.  Each hash reference has
 242 the following keys: invnum, date, owed
 243
 244 =item small_custview
 245
 246 An HTML fragment containing shipping and billing addresses.
 247
 248 =item The following fields are also returned: first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax
 249
 250 =back
 251
 252 =item edit_info HASHREF
 253
 254 Takes a hash reference as parameter with any of the following keys:
 255
 256 first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax
 257
 258 If a field exists, the customer record is updated with the new value of that
 259 field.  If a field does not exist, that field is not changed on the customer
 260 record.
 261
 262 Returns a hash reference with a single key, B<error>, empty on success, or an
 263 error message on errors
 264
 265 =item invoice HASHREF
 266
 267 Returns an invoice.  Takes a hash reference as parameter with two keys:
 268 session_id and invnum
 269
 270 Returns a hash reference with the following keys:
 271
 272 =over 4
 273
 274 =item error
 275
 276 Empty on success, or an error message on errors
 277
 278 =item invnum
 279
 280 Invoice number
 281
 282 =item invoice_text
 283
 284 Invoice text
 285
 286 =back
 287
 288 =item cancel HASHREF
 289
 290 Cancels this customer.
 291
 292 Takes a hash reference as parameter with a single key: B<session_id>
 293
 294 Returns a hash reference with a single key, B<error>, which is empty on
 295 success or an error message on errors.
 296
 297 =item payment_info HASHREF
 298
 299 Returns information that may be useful in displaying a payment page.
 300
 301 Takes a hash reference as parameter with a single key: B<session_id>.
 302
 303 Returns a hash reference with the following keys:
 304
 305 =over 4
 306
 307 =item error
 308
 309 Empty on success, or an error message on errors
 310
 311 =item balance
 312
 313 Balance owed
 314
 315 =item payname
 316
 317 Exact name on credit card (CARD/DCRD)
 318
 319 =item address1
 320
 321 =item address2
 322
 323 =item city
 324
 325 =item state
 326
 327 =item zip
 328
 329 =item payby
 330
 331 Customer's current default payment type.
 332
 333 =item card_type
 334
 335 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 336
 337 =item payinfo
 338
 339 For CARD/DCRD payment types, the card number
 340
 341 =item month
 342
 343 For CARD/DCRD payment types, expiration month
 344
 345 =item year
 346
 347 For CARD/DCRD payment types, expiration year
 348
 349 =item cust_main_county
 350
 351 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>).  Note these are not FS::cust_main_county objects, but hash references of columns and values.
 352
 353 =item states
 354
 355 Array reference of all states in the current default country.
 356
 357 =item card_types
 358
 359 Hash reference of card types; keys are card types, values are the exact strings
 360 passed to the process_payment function
 361
 362 =item paybatch
 363
 364 Unique transaction identifier (prevents multiple charges), passed to the
 365 process_payment function
 366
 367 =back
 368
 369 =item process_payment HASHREF
 370
 371 Processes a payment and possible change of address or payment type.  Takes a
 372 hash reference as parameter with the following keys:
 373
 374 =over 4
 375
 376 =item session_id
 377
 378 =item save
 379
 380 If true, address and card information entered will be saved for subsequent
 381 transactions.
 382
 383 =item auto
 384
 385 If true, future credit card payments will be done automatically (sets payby to
 386 CARD).  If false, future credit card payments will be done on-demand (sets
 387 payby to DCRD).  This option only has meaning if B<save> is set true.
 388
 389 =item payname
 390
 391 =item address1
 392
 393 =item address2
 394
 395 =item city
 396
 397 =item state
 398
 399 =item zip
 400
 401 =item payinfo
 402
 403 Card number
 404
 405 =item month
 406
 407 Card expiration month
 408
 409 =item year
 410
 411 Card expiration year
 412
 413 =item paybatch
 414
 415 Unique transaction identifier, returned from the payment_info function.
 416 Prevents multiple charges.
 417
 418 =back
 419
 420 Returns a hash reference with a single key, B<error>, empty on success, or an
 421 error message on errors
 422
 423 =item list_pkgs
 424
 425 Returns package information for this customer.
 426
 427 Takes a hash reference as parameter with a single key: B<session_id>
 428
 429 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 430
 431 =over 4
 432
 433 =item cust_pkg HASHREF
 434
 435 Array reference of hash references, each of which has the fields of a cust_pkg record (see L<FS::cust_pkg>).  Note these are not FS::cust_pkg objects, but hash references of columns and values.
 436
 437 =back
 438
 439 =item order_pkg
 440
 441 Orders a package for this customer.
 442
 443 Takes a hash reference as parameter with the following keys:
 444
 445 =over 4
 446
 447 =item session_id
 448
 449 =item pkgpart
 450
 451 =item svcpart
 452
 453 optional svcpart, required only if the package definition does not contain
 454 one svc_acct service definition with quantity 1 (it may contain others with
 455 quantity >1)
 456
 457 =item username
 458
 459 =item _password
 460
 461 =item sec_phrase
 462
 463 =item popnum
 464
 465 =back
 466
 467 Returns a hash reference with a single key, B<error>, empty on success, or an
 468 error message on errors.  The special error '_decline' is returned for
 469 declined transactions.
 470
 471 =item cancel_pkg
 472
 473 Cancels a package for this customer.
 474
 475 Takes a hash reference as parameter with the following keys:
 476
 477 =over 4
 478
 479 =item session_id
 480
 481 =item pkgpart
 482
 483 =back
 484
 485 Returns a hash reference with a single key, B<error>, empty on success, or an
 486 error message on errors.
 487
 488 =back
 489
 490 =head1 SIGNUP FUNCTIONS
 491
 492 =over 4
 493
 494 =item signup_info
 495
 496 Returns a hash reference containing information that may be useful in
 497 displaying a signup page.  The hash reference contains the following keys:
 498
 499 =over 4
 500
 501 =item cust_main_county
 502
 503 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>).  Note these are not FS::cust_main_county objects, but hash references of columns and values.
 504
 505 =item part_pkg
 506
 507 Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see L<FS::part_pkg>).  Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and L<FS::part_pkg/payby>).  Note these are not FS::part_pkg objects, but hash references of columns and values.  Requires the 'signup_server-default_agentnum' configuration value to be set.
 508
 509 =item agent
 510
 511 Array reference of hash references, each of which has the fields of an agent record (see L<FS::agent>).  Note these are not FS::agent objects, but hash references of columns and values.
 512
 513 =item agentnum2part_pkg
 514
 515 Hash reference; keys are agentnums, values are array references of available packages for that agent, in the same format as the part_pkg arrayref above.
 516
 517 =item svc_acct_pop
 518
 519 Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see L<FS::svc_acct_pop>).  Note these are not FS::svc_acct_pop objects, but hash references of columns and values.
 520
 521 =item security_phrase
 522
 523 True if the "security_phrase" feature is enabled
 524
 525 =item payby
 526
 527 Array reference of acceptable payment types for signup
 528
 529 =over 4
 530
 531 =item CARD (credit card - automatic)
 532
 533 =item DCRD (credit card - on-demand - version 1.5+ only)
 534
 535 =item CHEK (electronic check - automatic)
 536
 537 =item DCHK (electronic check - on-demand - version 1.5+ only)
 538
 539 =item LECB (Phone bill billing)
 540
 541 =item BILL (billing, not recommended for signups)
 542
 543 =item COMP (free, definately not recommended for signups)
 544
 545 =item PREPAY (special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL)
 546
 547 =back
 548
 549 =item cvv_enabled
 550
 551 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
 552
 553 =item msgcat
 554
 555 Hash reference of message catalog values, to support error message customization.  Currently available keys are: passwords_dont_match, invalid_card, unknown_card_type, and not_a (as in "Not a Discover card").  Values are configured in the web interface under "View/Edit message catalog".
 556
 557 =item statedefault
 558
 559 Default state
 560
 561 =item countrydefault
 562
 563 Default country
 564
 565 =back
 566
 567 =item new_customer HASHREF
 568
 569 Creates a new customer.  Takes a hash reference as parameter with the
 570 following keys:
 571
 572 =over 4
 573
 574 =item first - first name (required)
 575
 576 =item last - last name (required)
 577
 578 =item ss (not typically collected; mostly used for ACH transactions)
 579
 580 =item company
 581
 582 =item address1 (required)
 583
 584 =item address2
 585
 586 =item city (required)
 587
 588 =item county
 589
 590 =item state (required)
 591
 592 =item zip (required)
 593
 594 =item daytime - phone
 595
 596 =item night - phone
 597
 598 =item fax - phone
 599
 600 =item payby - CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
 601
 602 =item payinfo - Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
 603
 604 =item paycvv - Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
 605
 606 =item paydate - Expiration date for CARD/DCRD
 607
 608 =item payname - Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 609
 610 =item invoicing_list - comma-separated list of email addresses for email invoices.  The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
 611
 612 =item referral_custnum - referring customer number
 613
 614 =item pkgpart - pkgpart of initial package
 615
 616 =item username
 617
 618 =item _password
 619
 620 =item sec_phrase - security phrase
 621
 622 =item popnum - access number (index, not the literal number)
 623
 624 =item agentnum - agent number
 625
 626 =back
 627
 628 Returns a hash reference with the following keys:
 629
 630 =over 4
 631
 632 =item error Empty on success, or an error message on errors.  The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Sysadmin | View/Edit message catalog)
 633
 634 =back
 635
 636
 637 =back
 638
 639 =head1 BUGS
 640
 641 =head1 SEE ALSO
 642
 643 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
 644
 645 =cut
 646
 647 1;
 648