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