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