fs_selfservice/FS-SelfService/SelfService.pm

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