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