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