fs_selfservice/FS-SelfService/SelfService.pm

   1 package FS::SelfService;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT_OK $DEBUG $dir $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 $DEBUG = 0;
  17
  18 $dir = "/usr/local/freeside";
  19 $socket =  "$dir/selfservice_socket";
  20 $socket .= '.'.$tag if defined $tag && length($tag);
  21
  22 #maybe should ask ClientAPI for this list
  23 %autoload = (
  24   'passwd'                    => 'passwd/passwd',
  25   'chfn'                      => 'passwd/passwd',
  26   'chsh'                      => 'passwd/passwd',
  27   'login'                     => 'MyAccount/login',
  28   'logout'                    => 'MyAccount/logout',
  29   'customer_info'             => 'MyAccount/customer_info',
  30   'edit_info'                 => 'MyAccount/edit_info',     #add to ss cgi!
  31   'invoice'                   => 'MyAccount/invoice',
  32   'invoice_logo'              => 'MyAccount/invoice_logo',
  33   'list_invoices'             => 'MyAccount/list_invoices', #?
  34   'cancel'                    => 'MyAccount/cancel',        #add to ss cgi!
  35   'payment_info'              => 'MyAccount/payment_info',
  36   'payment_info_renew_info'   => 'MyAccount/payment_info_renew_info',
  37   'process_payment'           => 'MyAccount/process_payment',
  38   'process_payment_order_pkg' => 'MyAccount/process_payment_order_pkg',
  39   'process_payment_change_pkg' => 'MyAccount/process_payment_change_pkg',
  40   'process_payment_order_renew' => 'MyAccount/process_payment_order_renew',
  41   'process_prepay'            => 'MyAccount/process_prepay',
  42   'list_pkgs'                 => 'MyAccount/list_pkgs',     #add to ss (added?)
  43   'list_svcs'                 => 'MyAccount/list_svcs',     #add to ss (added?)
  44   'list_svc_usage'            => 'MyAccount/list_svc_usage',
  45   'order_pkg'                 => 'MyAccount/order_pkg',     #add to ss cgi!
  46   'change_pkg'                => 'MyAccount/change_pkg',
  47   'order_recharge'            => 'MyAccount/order_recharge',
  48   'renew_info'                => 'MyAccount/renew_info',
  49   'order_renew'               => 'MyAccount/order_renew',
  50   'cancel_pkg'                => 'MyAccount/cancel_pkg',    #add to ss cgi!
  51   'charge'                    => 'MyAccount/charge',        #?
  52   'part_svc_info'             => 'MyAccount/part_svc_info',
  53   'provision_acct'            => 'MyAccount/provision_acct',
  54   'provision_external'        => 'MyAccount/provision_external',
  55   'unprovision_svc'           => 'MyAccount/unprovision_svc',
  56   'myaccount_passwd'          => 'MyAccount/myaccount_passwd',
  57   'signup_info'               => 'Signup/signup_info',
  58   'domain_select_hash'        => 'Signup/domain_select_hash',  # expose?
  59   'new_customer'              => 'Signup/new_customer',
  60   'agent_login'               => 'Agent/agent_login',
  61   'agent_logout'              => 'Agent/agent_logout',
  62   'agent_info'                => 'Agent/agent_info',
  63   'agent_list_customers'      => 'Agent/agent_list_customers',
  64   #sg
  65   'ping'                      => 'SGNG/ping',
  66   'decompify_pkgs'            => 'SGNG/decompify_pkgs',
  67   'previous_payment_info'     => 'SGNG/previous_payment_info',
  68   'previous_payment_info_renew_info'
  69                               => 'SGNG/previous_payment_info_renew_info',
  70   'previous_process_payment'  => 'SGNG/previous_process_payment',
  71   'previous_process_payment_order_pkg'
  72                               => 'SGNG/previous_process_payment_order_pkg',
  73   'previous_process_payment_change_pkg'
  74                               => 'SGNG/previous_process_payment_change_pkg',
  75   'previous_process_payment_order_renew'
  76                               => 'SGNG/previous_process_payment_order_renew',
  77 );
  78 @EXPORT_OK = ( keys(%autoload), qw( regionselector expselect popselector domainselector) );
  79
  80 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
  81 $ENV{'SHELL'} = '/bin/sh';
  82 $ENV{'IFS'} = " \t\n";
  83 $ENV{'CDPATH'} = '';
  84 $ENV{'ENV'} = '';
  85 $ENV{'BASH_ENV'} = '';
  86
  87 my $freeside_uid = scalar(getpwnam('freeside'));
  88 die "not running as the freeside user\n" if $> != $freeside_uid;
  89
  90 -e $dir or die "FATAL: $dir doesn't exist!";
  91 -d $dir or die "FATAL: $dir isn't a directory!";
  92 -r $dir or die "FATAL: Can't read $dir as freeside user!";
  93 -x $dir or die "FATAL: $dir not searchable (executable) as freeside user!";
  94
  95 foreach my $autoload ( keys %autoload ) {
  96
  97   my $eval =
  98   "sub $autoload { ". '
  99                    my $param;
 100                    if ( ref($_[0]) ) {
 101                      $param = shift;
 102                    } else {
 103                      #warn scalar(@_). ": ". join(" / ", @_);
 104                      $param = { @_ };
 105                    }
 106
 107                    $param->{_packet} = \''. $autoload{$autoload}. '\';
 108
 109                    simple_packet($param);
 110                  }';
 111
 112   eval $eval;
 113   die $@ if $@;
 114
 115 }
 116
 117 sub simple_packet {
 118   my $packet = shift;
 119   warn "sending ". $packet->{_packet}. " to server"
 120     if $DEBUG;
 121   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
 122   connect(SOCK, sockaddr_un($socket)) or die "connect to $socket: $!";
 123   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
 124   SOCK->flush;
 125
 126   #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
 127
 128   #block until there is a message on socket
 129 #  my $w = new IO::Select;
 130 #  $w->add(\*SOCK);
 131 #  my @wait = $w->can_read;
 132
 133   warn "reading message from server"
 134     if $DEBUG;
 135
 136   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
 137   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
 138
 139   warn "returning message to client"
 140     if $DEBUG;
 141
 142   $return;
 143 }
 144
 145 =head1 NAME
 146
 147 FS::SelfService - Freeside self-service API
 148
 149 =head1 SYNOPSIS
 150
 151   # password and shell account changes
 152   use FS::SelfService qw(passwd chfn chsh);
 153
 154   # "my account" functionality
 155   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
 156
 157   my $rv = login( { 'username' => $username,
 158                     'domain'   => $domain,
 159                     'password' => $password,
 160                   }
 161                 );
 162
 163   if ( $rv->{'error'} ) {
 164     #handle login error...
 165   } else {
 166     #successful login
 167     my $session_id = $rv->{'session_id'};
 168   }
 169
 170   my $customer_info = customer_info( { 'session_id' => $session_id } );
 171
 172   #payment_info and process_payment are available in 1.5+ only
 173   my $payment_info = payment_info( { 'session_id' => $session_id } );
 174
 175   #!!! process_payment example
 176
 177   #!!! list_pkgs example
 178
 179   #!!! order_pkg example
 180
 181   #!!! cancel_pkg example
 182
 183   # signup functionality
 184   use FS::SelfService qw( signup_info new_customer );
 185
 186   my $signup_info = signup_info;
 187
 188   $rv = new_customer( {
 189                         'first'            => $first,
 190                         'last'             => $last,
 191                         'company'          => $company,
 192                         'address1'         => $address1,
 193                         'address2'         => $address2,
 194                         'city'             => $city,
 195                         'state'            => $state,
 196                         'zip'              => $zip,
 197                         'country'          => $country,
 198                         'daytime'          => $daytime,
 199                         'night'            => $night,
 200                         'fax'              => $fax,
 201                         'payby'            => $payby,
 202                         'payinfo'          => $payinfo,
 203                         'paycvv'           => $paycvv,
 204                         'paystart_month'   => $paystart_month
 205                         'paystart_year'    => $paystart_year,
 206                         'payissue'         => $payissue,
 207                         'payip'            => $payip
 208                         'paydate'          => $paydate,
 209                         'payname'          => $payname,
 210                         'invoicing_list'   => $invoicing_list,
 211                         'referral_custnum' => $referral_custnum,
 212                         'pkgpart'          => $pkgpart,
 213                         'username'         => $username,
 214                         '_password'        => $password,
 215                         'popnum'           => $popnum,
 216                         'agentnum'         => $agentnum,
 217                       }
 218                     );
 219
 220   my $error = $rv->{'error'};
 221   if ( $error eq '_decline' ) {
 222     print_decline();
 223   } elsif ( $error ) {
 224     reprint_signup();
 225   } else {
 226     print_success();
 227   }
 228
 229 =head1 DESCRIPTION
 230
 231 Use this API to implement your own client "self-service" module.
 232
 233 If you just want to customize the look of the existing "self-service" module,
 234 see XXXX instead.
 235
 236 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 237
 238 =over 4
 239
 240 =item passwd
 241
 242 =item chfn
 243
 244 =item chsh
 245
 246 =back
 247
 248 =head1 "MY ACCOUNT" FUNCTIONS
 249
 250 =over 4
 251
 252 =item login HASHREF
 253
 254 Creates a user session.  Takes a hash reference as parameter with the
 255 following keys:
 256
 257 =over 4
 258
 259 =item username
 260
 261 Username
 262
 263 =item domain
 264
 265 Domain
 266
 267 =item password
 268
 269 Password
 270
 271 =back
 272
 273 Returns a hash reference with the following keys:
 274
 275 =over 4
 276
 277 =item error
 278
 279 Empty on success, or an error message on errors.
 280
 281 =item session_id
 282
 283 Session identifier for successful logins
 284
 285 =back
 286
 287 =item customer_info HASHREF
 288
 289 Returns general customer information.
 290
 291 Takes a hash reference as parameter with a single key: B<session_id>
 292
 293 Returns a hash reference with the following keys:
 294
 295 =over 4
 296
 297 =item name
 298
 299 Customer name
 300
 301 =item balance
 302
 303 Balance owed
 304
 305 =item open
 306
 307 Array reference of hash references of open inoices.  Each hash reference has
 308 the following keys: invnum, date, owed
 309
 310 =item small_custview
 311
 312 An HTML fragment containing shipping and billing addresses.
 313
 314 =item The following fields are also returned
 315
 316 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 payby payinfo payname month year invoicing_list postal_invoicing
 317
 318 =back
 319
 320 =item edit_info HASHREF
 321
 322 Takes a hash reference as parameter with any of the following keys:
 323
 324 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 payby payinfo paycvv payname month year invoicing_list postal_invoicing
 325
 326 If a field exists, the customer record is updated with the new value of that
 327 field.  If a field does not exist, that field is not changed on the customer
 328 record.
 329
 330 Returns a hash reference with a single key, B<error>, empty on success, or an
 331 error message on errors
 332
 333 =item invoice HASHREF
 334
 335 Returns an invoice.  Takes a hash reference as parameter with two keys:
 336 session_id and invnum
 337
 338 Returns a hash reference with the following keys:
 339
 340 =over 4
 341
 342 =item error
 343
 344 Empty on success, or an error message on errors
 345
 346 =item invnum
 347
 348 Invoice number
 349
 350 =item invoice_text
 351
 352 Invoice text
 353
 354 =back
 355
 356 =item list_invoices HASHREF
 357
 358 Returns a list of all customer invoices.  Takes a hash references with a single
 359 key, session_id.
 360
 361 Returns a hash reference with the following keys:
 362
 363 =over 4
 364
 365 =item error
 366
 367 Empty on success, or an error message on errors
 368
 369 =item invoices
 370
 371 Reference to array of hash references with the following keys:
 372
 373 =over 4
 374
 375 =item invnum
 376
 377 Invoice ID
 378
 379 =item _date
 380
 381 Invoice date, in UNIX epoch time
 382
 383 =back
 384
 385 =back
 386
 387 =item cancel HASHREF
 388
 389 Cancels this customer.
 390
 391 Takes a hash reference as parameter with a single key: B<session_id>
 392
 393 Returns a hash reference with a single key, B<error>, which is empty on
 394 success or an error message on errors.
 395
 396 =item payment_info HASHREF
 397
 398 Returns information that may be useful in displaying a payment page.
 399
 400 Takes a hash reference as parameter with a single key: B<session_id>.
 401
 402 Returns a hash reference with the following keys:
 403
 404 =over 4
 405
 406 =item error
 407
 408 Empty on success, or an error message on errors
 409
 410 =item balance
 411
 412 Balance owed
 413
 414 =item payname
 415
 416 Exact name on credit card (CARD/DCRD)
 417
 418 =item address1
 419
 420 Address line one
 421
 422 =item address2
 423
 424 Address line two
 425
 426 =item city
 427
 428 City
 429
 430 =item state
 431
 432 State
 433
 434 =item zip
 435
 436 Zip or postal code
 437
 438 =item payby
 439
 440 Customer's current default payment type.
 441
 442 =item card_type
 443
 444 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 445
 446 =item payinfo
 447
 448 For CARD/DCRD payment types, the card number
 449
 450 =item month
 451
 452 For CARD/DCRD payment types, expiration month
 453
 454 =item year
 455
 456 For CARD/DCRD payment types, expiration year
 457
 458 =item cust_main_county
 459
 460 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.
 461
 462 =item states
 463
 464 Array reference of all states in the current default country.
 465
 466 =item card_types
 467
 468 Hash reference of card types; keys are card types, values are the exact strings
 469 passed to the process_payment function
 470
 471 =cut
 472
 473 #this doesn't actually work yet
 474 #
 475 #=item paybatch
 476 #
 477 #Unique transaction identifier (prevents multiple charges), passed to the
 478 #process_payment function
 479
 480 =back
 481
 482 =item process_payment HASHREF
 483
 484 Processes a payment and possible change of address or payment type.  Takes a
 485 hash reference as parameter with the following keys:
 486
 487 =over 4
 488
 489 =item session_id
 490
 491 Session identifier
 492
 493 =item amount
 494
 495 Amount
 496
 497 =item save
 498
 499 If true, address and card information entered will be saved for subsequent
 500 transactions.
 501
 502 =item auto
 503
 504 If true, future credit card payments will be done automatically (sets payby to
 505 CARD).  If false, future credit card payments will be done on-demand (sets
 506 payby to DCRD).  This option only has meaning if B<save> is set true.
 507
 508 =item payname
 509
 510 Name on card
 511
 512 =item address1
 513
 514 Address line one
 515
 516 =item address2
 517
 518 Address line two
 519
 520 =item city
 521
 522 City
 523
 524 =item state
 525
 526 State
 527
 528 =item zip
 529
 530 Zip or postal code
 531
 532 =item payinfo
 533
 534 Card number
 535
 536 =item month
 537
 538 Card expiration month
 539
 540 =item year
 541
 542 Card expiration year
 543
 544 =cut
 545
 546 #this doesn't actually work yet
 547 #
 548 #=item paybatch
 549 #
 550 #Unique transaction identifier, returned from the payment_info function.
 551 #Prevents multiple charges.
 552
 553 =back
 554
 555 Returns a hash reference with a single key, B<error>, empty on success, or an
 556 error message on errors.
 557
 558 =item process_payment_order_pkg
 559
 560 Combines the B<process_payment> and B<order_pkg> functions in one step.  If the
 561 payment processes sucessfully, the package is ordered.  Takes a hash reference
 562 as parameter with the keys of both methods.
 563
 564 Returns a hash reference with a single key, B<error>, empty on success, or an
 565 error message on errors.
 566
 567 =item process_payment_change_pkg
 568
 569 Combines the B<process_payment> and B<change_pkg> functions in one step.  If the
 570 payment processes sucessfully, the package is ordered.  Takes a hash reference
 571 as parameter with the keys of both methods.
 572
 573 Returns a hash reference with a single key, B<error>, empty on success, or an
 574 error message on errors.
 575
 576
 577 =item process_payment_order_renew
 578
 579 Combines the B<process_payment> and B<order_renew> functions in one step.  If
 580 the payment processes sucessfully, the renewal is processed.  Takes a hash
 581 reference as parameter with the keys of both methods.
 582
 583 Returns a hash reference with a single key, B<error>, empty on success, or an
 584 error message on errors.
 585
 586 =item list_pkgs
 587
 588 Returns package information for this customer.  For more detail on services,
 589 see L</list_svcs>.
 590
 591 Takes a hash reference as parameter with a single key: B<session_id>
 592
 593 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 594
 595 =over 4
 596
 597 =item custnum
 598
 599 Customer number
 600
 601 =item error
 602
 603 Empty on success, or an error message on errors.
 604
 605 =item cust_pkg HASHREF
 606
 607 Array reference of hash references, each of which has the fields of a cust_pkg
 608 record (see L<FS::cust_pkg>) as well as the fields below.  Note these are not
 609 the internal FS:: objects, but hash references of columns and values.
 610
 611 =over 4
 612
 613 =item part_pkg fields
 614
 615 All fields of part_pkg for this specific cust_pkg (be careful with this
 616 information - it may reveal more about your available packages than you would
 617 like users to know in aggregate)
 618
 619 =cut
 620
 621 #XXX pare part_pkg fields down to a more secure subset
 622
 623 =item part_svc
 624
 625 An array of hash references indicating information on unprovisioned services
 626 available for provisioning for this specific cust_pkg.  Each has the following
 627 keys:
 628
 629 =over 4
 630
 631 =item part_svc fields
 632
 633 All fields of part_svc (be careful with this information - it may reveal more
 634 about your available packages than you would like users to know in aggregate)
 635
 636 =cut
 637
 638 #XXX pare part_svc fields down to a more secure subset
 639
 640 =back
 641
 642 =item cust_svc
 643
 644 An array of hash references indicating information on the customer services
 645 already provisioned for this specific cust_pkg.  Each has the following keys:
 646
 647 =over 4
 648
 649 =item label
 650
 651 Array reference with three elements: The first element is the name of this service.  The second element is a meaningful user-specific identifier for the service (i.e. username, domain or mail alias).  The last element is the table name of this service.
 652
 653 =back
 654
 655 =item svcnum
 656
 657 Primary key for this service
 658
 659 =item svcpart
 660
 661 Service definition (see L<FS::part_svc>)
 662
 663 =item pkgnum
 664
 665 Customer package (see L<FS::cust_pkg>)
 666
 667 =item overlimit
 668
 669 Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).
 670
 671 =back
 672
 673 =back
 674
 675 =item list_svcs
 676
 677 Returns service information for this customer.
 678
 679 Takes a hash reference as parameter with a single key: B<session_id>
 680
 681 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 682
 683 =over 4
 684
 685 =item custnum
 686
 687 Customer number
 688
 689 =item svcs
 690
 691 An array of hash references indicating information on all of this customer's
 692 services.  Each has the following keys:
 693
 694 =over 4
 695
 696 =item svcnum
 697
 698 Primary key for this service
 699
 700 =item label
 701
 702 Name of this service
 703
 704 =item value
 705
 706 Meaningful user-specific identifier for the service (i.e. username, domain, or
 707 mail alias).
 708
 709 =back
 710
 711 Account (svc_acct) services also have the following keys:
 712
 713 =over 4
 714
 715 =item username
 716
 717 Username
 718
 719 =item email
 720
 721 username@domain
 722
 723 =item seconds
 724
 725 Seconds remaining
 726
 727 =item upbytes
 728
 729 Upload bytes remaining
 730
 731 =item downbytes
 732
 733 Download bytes remaining
 734
 735 =item totalbytes
 736
 737 Total bytes remaining
 738
 739 =item recharge_amount
 740
 741 Cost of a recharge
 742
 743 =item recharge_seconds
 744
 745 Number of seconds gained by recharge
 746
 747 =item recharge_upbytes
 748
 749 Number of upload bytes gained by recharge
 750
 751 =item recharge_downbytes
 752
 753 Number of download bytes gained by recharge
 754
 755 =item recharge_totalbytes
 756
 757 Number of total bytes gained by recharge
 758
 759 =back
 760
 761 =back
 762
 763 =item order_pkg
 764
 765 Orders a package for this customer.
 766
 767 Takes a hash reference as parameter with the following keys:
 768
 769 =over 4
 770
 771 =item session_id
 772
 773 Session identifier
 774
 775 =item pkgpart
 776
 777 pkgpart of package to order
 778
 779 =item svcpart
 780
 781 optional svcpart, required only if the package definition does not contain
 782 one svc_acct service definition with quantity 1 (it may contain others with
 783 quantity >1)
 784
 785 =item username
 786
 787 Username
 788
 789 =item _password
 790
 791 Password
 792
 793 =item sec_phrase
 794
 795 Optional security phrase
 796
 797 =item popnum
 798
 799 Optional Access number number
 800
 801 =back
 802
 803 Returns a hash reference with a single key, B<error>, empty on success, or an
 804 error message on errors.  The special error '_decline' is returned for
 805 declined transactions.
 806
 807 =item change_pkg
 808
 809 Changes a package for this customer.
 810
 811 Takes a hash reference as parameter with the following keys:
 812
 813 =over 4
 814
 815 =item session_id
 816
 817 Session identifier
 818
 819 =item pkgnum
 820
 821 Existing customer package.
 822
 823 =item pkgpart
 824
 825 New package to order (see L<FS::part_pkg>).
 826
 827 =back
 828
 829 Returns a hash reference with a single key, B<error>, empty on success, or an
 830 error message on errors.
 831
 832 =item renew_info
 833
 834 Provides useful info for early renewals.
 835
 836 Takes a hash reference as parameter with the following keys:
 837
 838 =over 4
 839
 840 =item session_id
 841
 842 Session identifier
 843
 844 =back
 845
 846 Returns a hash reference.  On errors, it contains a single key, B<error>, with
 847 the error message.  Otherwise, contains a single key, B<dates>, pointing to
 848 an array refernce of hash references.  Each hash reference contains the
 849 following keys:
 850
 851 =over 4
 852
 853 =item bill_date
 854
 855 (Future) Bill date.  Indicates a future date for which billing could be run.
 856 Specified as a integer UNIX timestamp.  Pass this value to the B<order_renew>
 857 function.
 858
 859 =item bill_date_pretty
 860
 861 (Future) Bill date as a human-readable string.  (Convenience for display;
 862 subject to change, so best not to parse for the date.)
 863
 864 =item amount
 865
 866 Base amount which will be charged if renewed early as of this date.
 867
 868 =item renew_date
 869
 870 Renewal date; i.e. even-futher future date at which the customer will be paid
 871 through if the early renewal is completed with the given B<bill-date>.
 872 Specified as a integer UNIX timestamp.
 873
 874 =item renew_date_pretty
 875
 876 Renewal date as a human-readable string.  (Convenience for display;
 877 subject to change, so best not to parse for the date.)
 878
 879 =item pkgnum
 880
 881 Package that will be renewed.
 882
 883 =item expire_date
 884
 885 Expiration date of the package that will be renewed.
 886
 887 =item expire_date_pretty
 888
 889 Expiration date of the package that will be renewed, as a human-readable
 890 string.  (Convenience for display; subject to change, so best not to parse for
 891 the date.)
 892
 893 =back
 894
 895 =item order_renew
 896
 897 Renews this customer early; i.e. runs billing for this customer in advance.
 898
 899 Takes a hash reference as parameter with the following keys:
 900
 901 =over 4
 902
 903 =item session_id
 904
 905 Session identifier
 906
 907 =item date
 908
 909 Integer date as returned by the B<renew_info> function, indicating the advance
 910 date for which to run billing.
 911
 912 =back
 913
 914 Returns a hash reference with a single key, B<error>, empty on success, or an
 915 error message on errors.
 916
 917 =item cancel_pkg
 918
 919 Cancels a package for this customer.
 920
 921 Takes a hash reference as parameter with the following keys:
 922
 923 =over 4
 924
 925 =item session_id
 926
 927 Session identifier
 928
 929 =item pkgpart
 930
 931 pkgpart of package to cancel
 932
 933 =back
 934
 935 Returns a hash reference with a single key, B<error>, empty on success, or an
 936 error message on errors.
 937
 938 =back
 939
 940 =head1 SIGNUP FUNCTIONS
 941
 942 =over 4
 943
 944 =item signup_info HASHREF
 945
 946 Takes a hash reference as parameter with the following keys:
 947
 948 =over 4
 949
 950 =item session_id - Optional agent/reseller interface session
 951
 952 =back
 953
 954 Returns a hash reference containing information that may be useful in
 955 displaying a signup page.  The hash reference contains the following keys:
 956
 957 =over 4
 958
 959 =item cust_main_county
 960
 961 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.
 962
 963 =item part_pkg
 964
 965 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, or
 966 an agentnum specified explicitly via reseller interface session_id in the
 967 options.
 968
 969 =item agent
 970
 971 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.
 972
 973 =item agentnum2part_pkg
 974
 975 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.
 976
 977 =item svc_acct_pop
 978
 979 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.
 980
 981 =item security_phrase
 982
 983 True if the "security_phrase" feature is enabled
 984
 985 =item payby
 986
 987 Array reference of acceptable payment types for signup
 988
 989 =over 4
 990
 991 =item CARD
 992
 993 credit card - automatic
 994
 995 =item DCRD
 996
 997 credit card - on-demand - version 1.5+ only
 998
 999 =item CHEK
1000
1001 electronic check - automatic
1002
1003 =item DCHK
1004
1005 electronic check - on-demand - version 1.5+ only
1006
1007 =item LECB
1008
1009 Phone bill billing
1010
1011 =item BILL
1012
1013 billing, not recommended for signups
1014
1015 =item COMP
1016
1017 free, definitely not recommended for signups
1018
1019 =item PREPAY
1020
1021 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1022
1023 =back
1024
1025 =item cvv_enabled
1026
1027 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1028
1029 =item msgcat
1030
1031 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".
1032
1033 =item statedefault
1034
1035 Default state
1036
1037 =item countrydefault
1038
1039 Default country
1040
1041 =back
1042
1043 =item new_customer HASHREF
1044
1045 Creates a new customer.  Takes a hash reference as parameter with the
1046 following keys:
1047
1048 =over 4
1049
1050 =item first
1051
1052 first name (required)
1053
1054 =item last
1055
1056 last name (required)
1057
1058 =item ss
1059
1060 (not typically collected; mostly used for ACH transactions)
1061
1062 =item company
1063
1064 Company name
1065
1066 =item address1 (required)
1067
1068 Address line one
1069
1070 =item address2
1071
1072 Address line two
1073
1074 =item city (required)
1075
1076 City
1077
1078 =item county
1079
1080 County
1081
1082 =item state (required)
1083
1084 State
1085
1086 =item zip (required)
1087
1088 Zip or postal code
1089
1090 =item daytime
1091
1092 Daytime phone number
1093
1094 =item night
1095
1096 Evening phone number
1097
1098 =item fax
1099
1100 Fax number
1101
1102 =item payby
1103
1104 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
1105
1106 =item payinfo
1107
1108 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
1109
1110 =item paycvv
1111
1112 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
1113
1114 =item paydate
1115
1116 Expiration date for CARD/DCRD
1117
1118 =item payname
1119
1120 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
1121
1122 =item invoicing_list
1123
1124 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),
1125
1126 =item referral_custnum
1127
1128 referring customer number
1129
1130 =item pkgpart
1131
1132 pkgpart of initial package
1133
1134 =item username
1135
1136 Username
1137
1138 =item _password
1139
1140 Password
1141
1142 =item sec_phrase
1143
1144 Security phrase
1145
1146 =item popnum
1147
1148 Access number (index, not the literal number)
1149
1150 =item agentnum
1151
1152 Agent number
1153
1154 =back
1155
1156 Returns a hash reference with the following keys:
1157
1158 =over 4
1159
1160 =item error
1161
1162 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 Configuration | View/Edit message catalog)
1163
1164 =back
1165
1166 =item regionselector HASHREF | LIST
1167
1168 Takes as input a hashref or list of key/value pairs with the following keys:
1169
1170 =over 4
1171
1172 =item selected_county
1173
1174 Currently selected county
1175
1176 =item selected_state
1177
1178 Currently selected state
1179
1180 =item selected_country
1181
1182 Currently selected country
1183
1184 =item prefix
1185
1186 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
1187
1188 =item onchange
1189
1190 Specify a javascript subroutine to call on changes
1191
1192 =item default_state
1193
1194 Default state
1195
1196 =item default_country
1197
1198 Default country
1199
1200 =item locales
1201
1202 An arrayref of hash references specifying regions.  Normally you can just pass the value of the I<cust_main_county> field returned by B<signup_info>.
1203
1204 =back
1205
1206 Returns a list consisting of three HTML fragments for county selection,
1207 state selection and country selection, respectively.
1208
1209 =cut
1210
1211 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
1212 sub regionselector {
1213   my $param;
1214   if ( ref($_[0]) ) {
1215     $param = shift;
1216   } else {
1217     $param = { @_ };
1218   }
1219   $param->{'selected_country'} ||= $param->{'default_country'};
1220   $param->{'selected_state'} ||= $param->{'default_state'};
1221
1222   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
1223
1224   my $countyflag = 0;
1225
1226   my %cust_main_county;
1227
1228 #  unless ( @cust_main_county ) { #cache
1229     #@cust_main_county = qsearch('cust_main_county', {} );
1230     #foreach my $c ( @cust_main_county ) {
1231     foreach my $c ( @{ $param->{'locales'} } ) {
1232       #$countyflag=1 if $c->county;
1233       $countyflag=1 if $c->{county};
1234       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
1235       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
1236       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
1237     }
1238 #  }
1239   $countyflag=1 if $param->{selected_county};
1240
1241   my $script_html = <<END;
1242     <SCRIPT>
1243     function opt(what,value,text) {
1244       var optionName = new Option(text, value, false, false);
1245       var length = what.length;
1246       what.options[length] = optionName;
1247     }
1248     function ${prefix}country_changed(what) {
1249       country = what.options[what.selectedIndex].text;
1250       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
1251           what.form.${prefix}state.options[i] = null;
1252 END
1253       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
1254
1255   foreach my $country ( sort keys %cust_main_county ) {
1256     $script_html .= "\nif ( country == \"$country\" ) {\n";
1257     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
1258       my $text = $state || '(n/a)';
1259       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
1260     }
1261     $script_html .= "}\n";
1262   }
1263
1264   $script_html .= <<END;
1265     }
1266     function ${prefix}state_changed(what) {
1267 END
1268
1269   if ( $countyflag ) {
1270     $script_html .= <<END;
1271       state = what.options[what.selectedIndex].text;
1272       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
1273       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
1274           what.form.${prefix}county.options[i] = null;
1275 END
1276
1277     foreach my $country ( sort keys %cust_main_county ) {
1278       $script_html .= "\nif ( country == \"$country\" ) {\n";
1279       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
1280         $script_html .= "\nif ( state == \"$state\" ) {\n";
1281           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
1282           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
1283             my $text = $county || '(n/a)';
1284             $script_html .=
1285               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
1286           }
1287         $script_html .= "}\n";
1288       }
1289       $script_html .= "}\n";
1290     }
1291   }
1292
1293   $script_html .= <<END;
1294     }
1295     </SCRIPT>
1296 END
1297
1298   my $county_html = $script_html;
1299   if ( $countyflag ) {
1300     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
1301     $county_html .= '</SELECT>';
1302   } else {
1303     $county_html .=
1304       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
1305   }
1306
1307   my $state_html = qq!<SELECT NAME="${prefix}state" !.
1308                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
1309   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
1310     my $text = $state || '(n/a)';
1311     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
1312     $state_html .= "\n<OPTION $selected VALUE=$state>$text</OPTION>"
1313   }
1314   $state_html .= '</SELECT>';
1315
1316   $state_html .= '</SELECT>';
1317
1318   my $country_html = qq!<SELECT NAME="${prefix}country" !.
1319                      qq!onChange="${prefix}country_changed(this); $param->{'onchange'}">!;
1320   my $countrydefault = $param->{default_country} || 'US';
1321   foreach my $country (
1322     sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
1323       keys %cust_main_county
1324   ) {
1325     my $selected = $country eq $param->{'selected_country'} ? ' SELECTED' : '';
1326     $country_html .= "\n<OPTION$selected>$country</OPTION>"
1327   }
1328   $country_html .= '</SELECT>';
1329
1330   ($county_html, $state_html, $country_html);
1331
1332 }
1333
1334 #=item expselect HASHREF | LIST
1335 #
1336 #Takes as input a hashref or list of key/value pairs with the following keys:
1337 #
1338 #=over 4
1339 #
1340 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
1341 #
1342 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
1343 #
1344 #=back
1345
1346 =item expselect PREFIX [ DATE ]
1347
1348 Takes as input a unique prefix string and the current expiration date, in
1349 yyyy-mm-dd or m-d-yyyy format
1350
1351 Returns an HTML fragments for expiration date selection.
1352
1353 =cut
1354
1355 sub expselect {
1356   #my $param;
1357   #if ( ref($_[0]) ) {
1358   #  $param = shift;
1359   #} else {
1360   #  $param = { @_ };
1361   #my $prefix = $param->{'prefix'};
1362   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
1363   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
1364   my $prefix = shift;
1365   my $date = scalar(@_) ? shift : '';
1366
1367   my( $m, $y ) = ( 0, 0 );
1368   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
1369     ( $m, $y ) = ( $2, $1 );
1370   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
1371     ( $m, $y ) = ( $1, $3 );
1372   }
1373   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
1374   for ( 1 .. 12 ) {
1375     $return .= qq!<OPTION VALUE="$_"!;
1376     $return .= " SELECTED" if $_ == $m;
1377     $return .= ">$_";
1378   }
1379   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
1380   my @t = localtime;
1381   my $thisYear = $t[5] + 1900;
1382   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
1383     $return .= qq!<OPTION VALUE="$_"!;
1384     $return .= " SELECTED" if $_ == $y;
1385     $return .= ">$_";
1386   }
1387   $return .= "</SELECT>";
1388
1389   $return;
1390 }
1391
1392 =item popselector HASHREF | LIST
1393
1394 Takes as input a hashref or list of key/value pairs with the following keys:
1395
1396 =over 4
1397
1398 =item popnum
1399
1400 Access number number
1401
1402 =item pops
1403
1404 An arrayref of hash references specifying access numbers.  Normally you can just pass the value of the I<svc_acct_pop> field returned by B<signup_info>.
1405
1406 =back
1407
1408 Returns an HTML fragment for access number selection.
1409
1410 =cut
1411
1412 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
1413 sub popselector {
1414   my $param;
1415   if ( ref($_[0]) ) {
1416     $param = shift;
1417   } else {
1418     $param = { @_ };
1419   }
1420   my $popnum = $param->{'popnum'};
1421   my $pops = $param->{'pops'};
1422
1423   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
1424   return $pops->[0]{city}. ', '. $pops->[0]{state}.
1425          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
1426          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
1427     if scalar(@$pops) == 1;
1428
1429   my %pop = ();
1430   my %popnum2pop = ();
1431   foreach (@$pops) {
1432     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
1433     $popnum2pop{$_->{popnum}} = $_;
1434   }
1435
1436   my $text = <<END;
1437     <SCRIPT>
1438     function opt(what,href,text) {
1439       var optionName = new Option(text, href, false, false)
1440       var length = what.length;
1441       what.options[length] = optionName;
1442     }
1443 END
1444
1445   my $init_popstate = $param->{'init_popstate'};
1446   if ( $init_popstate ) {
1447     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
1448              $init_popstate. '">';
1449   } else {
1450     $text .= <<END;
1451       function acstate_changed(what) {
1452         state = what.options[what.selectedIndex].text;
1453         what.form.popac.options.length = 0
1454         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
1455 END
1456   }
1457
1458   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
1459   foreach my $state ( sort { $a cmp $b } @states ) {
1460     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
1461
1462     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
1463       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
1464       if ($ac eq $param->{'popac'}) {
1465         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
1466       }
1467     }
1468     $text .= "}\n" unless $init_popstate;
1469   }
1470   $text .= "popac_changed(what.form.popac)}\n";
1471
1472   $text .= <<END;
1473   function popac_changed(what) {
1474     ac = what.options[what.selectedIndex].text;
1475     what.form.popnum.options.length = 0;
1476     what.form.popnum.options[0] = new Option("City", "-1", false, true);
1477
1478 END
1479
1480   foreach my $state ( @states ) {
1481     foreach my $popac ( keys %{ $pop{$state} } ) {
1482       $text .= "\nif ( ac == \"$popac\" ) {\n";
1483
1484       foreach my $pop ( @{$pop{$state}->{$popac}}) {
1485         my $o_popnum = $pop->{popnum};
1486         my $poptext =  $pop->{city}. ', '. $pop->{state}.
1487                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
1488
1489         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
1490         if ($popnum == $o_popnum) {
1491           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
1492         }
1493       }
1494       $text .= "}\n";
1495     }
1496   }
1497
1498
1499   $text .= "}\n</SCRIPT>\n";
1500
1501   $text .=
1502     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
1503     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
1504   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
1505            ">$_" foreach sort { $a cmp $b } @states;
1506   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
1507
1508   $text .=
1509     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
1510     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
1511
1512   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
1513
1514
1515   #comment this block to disable initial list polulation
1516   my @initial_select = ();
1517   if ( scalar( @$pops ) > 100 ) {
1518     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
1519   } else {
1520     @initial_select = @$pops;
1521   }
1522   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
1523     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
1524              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
1525              $pop->{city}. ', '. $pop->{state}.
1526                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
1527   }
1528
1529   $text .= qq!</SELECT></TD></TR></TABLE>!;
1530
1531   $text;
1532
1533 }
1534
1535 =item domainselector HASHREF | LIST
1536
1537 Takes as input a hashref or list of key/value pairs with the following keys:
1538
1539 =over 4
1540
1541 =item pkgnum
1542
1543 Package number
1544
1545 =item domsvc
1546
1547 Service number of the selected item.
1548
1549 =back
1550
1551 Returns an HTML fragment for domain selection.
1552
1553 =cut
1554
1555 sub domainselector {
1556   my $param;
1557   if ( ref($_[0]) ) {
1558     $param = shift;
1559   } else {
1560     $param = { @_ };
1561   }
1562   my $domsvc= $param->{'domsvc'};
1563   my $rv =
1564       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
1565   my $domains = $rv->{'domains'};
1566   $domsvc = $rv->{'domsvc'} unless $domsvc;
1567
1568   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
1569     unless scalar(keys %$domains);
1570
1571   if (scalar(keys %$domains) == 1) {
1572     my $key;
1573     foreach(keys %$domains) {
1574       $key = $_;
1575     }
1576     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
1577            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
1578   }
1579
1580   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em"><OPTION>(Choose Domain)!;
1581
1582
1583   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
1584     $text .= qq!<OPTION VALUE="!. $domain. '"'.
1585              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
1586              $domains->{$domain};
1587   }
1588
1589   $text .= qq!</SELECT></TD></TR>!;
1590
1591   $text;
1592
1593 }
1594
1595 =back
1596
1597 =head1 RESELLER FUNCTIONS
1598
1599 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
1600 with their active session, and the B<customer_info> and B<order_pkg> functions
1601 with their active session and an additional I<custnum> parameter.
1602
1603 For the most part, development of the reseller web interface has been
1604 superceded by agent-virtualized access to the backend.
1605
1606 =over 4
1607
1608 =item agent_login
1609
1610 Agent login
1611
1612 =item agent_info
1613
1614 Agent info
1615
1616 =item agent_list_customers
1617
1618 List agent's customers.
1619
1620 =back
1621
1622 =head1 BUGS
1623
1624 =head1 SEE ALSO
1625
1626 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
1627
1628 =cut
1629
1630 1;
1631