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