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   'customer_recurring'        => 'MyAccount/customer_recurring',
  37
  38   'contact_passwd'            => 'MyAccount/contact/contact_passwd',
  39   'list_contacts'             => 'MyAccount/contact/list_contacts',
  40   'edit_contact'              => 'MyAccount/contact/edit_contact',
  41   'delete_contact'            => 'MyAccount/contact/delete_contact',
  42   'new_contact'               => 'MyAccount/contact/new_contact',
  43
  44   'billing_history'           => 'MyAccount/billing_history',
  45   'edit_info'                 => 'MyAccount/edit_info',     #add to ss cgi!
  46   'invoice'                   => 'MyAccount/invoice',
  47   'invoice_pdf'               => 'MyAccount/invoice_pdf',
  48   'legacy_invoice'            => 'MyAccount/legacy_invoice',
  49   'legacy_invoice_pdf'        => 'MyAccount/legacy_invoice_pdf',
  50   'invoice_logo'              => 'MyAccount/invoice_logo',
  51   'list_invoices'             => 'MyAccount/list_invoices', #?
  52   'list_payby'                => 'MyAccount/list_payby',
  53   'insert_payby'              => 'MyAccount/insert_payby',
  54   'update_payby'              => 'MyAccount/update_payby',
  55   'delete_payby'              => 'MyAccount/delete_payby',
  56   'cancel'                    => 'MyAccount/cancel',        #add to ss cgi!
  57   'payment_info'              => 'MyAccount/payment_info',
  58   'payment_info_renew_info'   => 'MyAccount/payment_info_renew_info',
  59   'process_payment'           => 'MyAccount/process_payment',
  60   'store_payment'             => 'MyAccount/store_payment',
  61   'process_stored_payment'    => 'MyAccount/process_stored_payment',
  62   'process_payment_order_pkg' => 'MyAccount/process_payment_order_pkg',
  63   'process_payment_change_pkg' => 'MyAccount/process_payment_change_pkg',
  64   'process_payment_order_renew' => 'MyAccount/process_payment_order_renew',
  65   'process_prepay'            => 'MyAccount/process_prepay',
  66   'realtime_collect'          => 'MyAccount/realtime_collect',
  67   'list_pkgs'                 => 'MyAccount/list_pkgs',     #add to ss (added?)
  68   'list_svcs'                 => 'MyAccount/list_svcs',     #add to ss (added?)
  69   'list_svc_usage'            => 'MyAccount/list_svc_usage',
  70   'svc_status_html'           => 'MyAccount/svc_status_html',
  71   'svc_status_hash'           => 'MyAccount/svc_status_hash',
  72   'set_svc_status_hash'       => 'MyAccount/set_svc_status_hash',
  73   'set_svc_status_listadd'    => 'MyAccount/set_svc_status_listadd',
  74   'set_svc_status_listdel'    => 'MyAccount/set_svc_status_listdel',
  75   'set_svc_status_vacationadd'=> 'MyAccount/set_svc_status_vacationadd',
  76   'set_svc_status_vacationdel'=> 'MyAccount/set_svc_status_vacationdel',
  77   'acct_forward_info'         => 'MyAccount/acct_forward_info',
  78   'process_acct_forward'      => 'MyAccount/process_acct_forward',
  79   'list_dsl_devices'          => 'MyAccount/list_dsl_devices',
  80   'add_dsl_device'            => 'MyAccount/add_dsl_device',
  81   'delete_dsl_device'         => 'MyAccount/delete_dsl_device',
  82   'port_graph'                => 'MyAccount/port_graph',
  83   'list_cdr_usage'            => 'MyAccount/list_cdr_usage',
  84   'list_support_usage'        => 'MyAccount/list_support_usage',
  85   'order_pkg'                 => 'MyAccount/order_pkg',     #add to ss cgi!
  86   'change_pkg'                => 'MyAccount/change_pkg',
  87   'order_recharge'            => 'MyAccount/order_recharge',
  88   'renew_info'                => 'MyAccount/renew_info',
  89   'order_renew'               => 'MyAccount/order_renew',
  90   'cancel_pkg'                => 'MyAccount/cancel_pkg',    #add to ss cgi!
  91   'suspend_pkg'               => 'MyAccount/suspend_pkg',   #add to ss cgi!
  92   'charge'                    => 'MyAccount/charge',        #?
  93   'part_svc_info'             => 'MyAccount/part_svc_info',
  94   'provision_acct'            => 'MyAccount/provision_acct',
  95   'provision_phone'           => 'MyAccount/provision_phone',
  96   'provision_pbx'             => 'MyAccount/provision_pbx',
  97   'provision_external'        => 'MyAccount/provision_external',
  98   'provision_forward'         => 'MyAccount/provision_forward',
  99   'unprovision_svc'           => 'MyAccount/unprovision_svc',
 100   'myaccount_passwd'          => 'MyAccount/myaccount_passwd',
 101   'reset_passwd'              => 'MyAccount/reset_passwd',
 102   'check_reset_passwd'        => 'MyAccount/check_reset_passwd',
 103   'process_reset_passwd'      => 'MyAccount/process_reset_passwd',
 104   'validate_passwd'           => 'MyAccount/validate_passwd',
 105   'list_tickets'              => 'MyAccount/list_tickets',
 106   'create_ticket'             => 'MyAccount/create_ticket',
 107   'get_ticket'                => 'MyAccount/get_ticket',
 108   'adjust_ticket_priority'    => 'MyAccount/adjust_ticket_priority',
 109   'did_report'                => 'MyAccount/did_report',
 110   'signup_info'               => 'Signup/signup_info',
 111   'skin_info'                 => 'MyAccount/skin_info',
 112   'access_info'               => 'MyAccount/access_info',
 113   'domain_select_hash'        => 'Signup/domain_select_hash',  # expose?
 114   'new_customer'              => 'Signup/new_customer',
 115   'new_customer_minimal'      => 'Signup/new_customer_minimal',
 116   'capture_payment'           => 'Signup/capture_payment',
 117   #N/A 'clear_signup_cache'        => 'Signup/clear_cache',
 118   'new_agent'                 => 'Agent/new_agent',
 119   'agent_login'               => 'Agent/agent_login',
 120   'agent_logout'              => 'Agent/agent_logout',
 121   'agent_info'                => 'Agent/agent_info',
 122   'agent_list_customers'      => 'Agent/agent_list_customers',
 123   'check_username'            => 'Agent/check_username',
 124   'suspend_username'          => 'Agent/suspend_username',
 125   'unsuspend_username'        => 'Agent/unsuspend_username',
 126   'mason_comp'                => 'MasonComponent/mason_comp',
 127   'call_time'                 => 'PrepaidPhone/call_time',
 128   'call_time_nanpa'           => 'PrepaidPhone/call_time_nanpa',
 129   'phonenum_balance'          => 'PrepaidPhone/phonenum_balance',
 130
 131   'start_thirdparty'          => 'MyAccount/start_thirdparty',
 132   'finish_thirdparty'         => 'MyAccount/finish_thirdparty',
 133
 134   'list_quotations'           => 'MyAccount/quotation/list_quotations',
 135   'quotation_new'             => 'MyAccount/quotation/quotation_new',
 136   'quotation_delete'          => 'MyAccount/quotation/quotation_delete',
 137   'quotation_info'            => 'MyAccount/quotation/quotation_info',
 138   'quotation_print'           => 'MyAccount/quotation/quotation_print',
 139   'quotation_add_pkg'         => 'MyAccount/quotation/quotation_add_pkg',
 140   'quotation_remove_pkg'      => 'MyAccount/quotation/quotation_remove_pkg',
 141   'quotation_order'           => 'MyAccount/quotation/quotation_order',
 142
 143   'freesideinc_service'       => 'Freeside/freesideinc_service',
 144
 145 );
 146 @EXPORT_OK = (
 147   keys(%autoload),
 148   qw( regionselector regionselector_hashref location_form
 149       expselect popselector domainselector didselector
 150     )
 151 );
 152
 153 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
 154 $ENV{'SHELL'} = '/bin/sh';
 155 $ENV{'IFS'} = " \t\n";
 156 $ENV{'CDPATH'} = '';
 157 $ENV{'ENV'} = '';
 158 $ENV{'BASH_ENV'} = '';
 159
 160 #you can add BEGIN { $FS::SelfService::skip_uid_check = 1; }
 161 #if you grant appropriate permissions to whatever user
 162 my $freeside_uid = scalar(getpwnam('freeside'));
 163 die "not running as the freeside user\n"
 164   if $> != $freeside_uid && ! $skip_uid_check;
 165
 166 -e $dir or die "FATAL: $dir doesn't exist!";
 167 -d $dir or die "FATAL: $dir isn't a directory!";
 168 -r $dir or die "FATAL: Can't read $dir as freeside user!";
 169 -x $dir or die "FATAL: $dir not searchable (executable) as freeside user!";
 170
 171 foreach my $autoload ( keys %autoload ) {
 172
 173   my $eval =
 174   "sub $autoload { ". '
 175                    my $param;
 176                    if ( ref($_[0]) ) {
 177                      $param = shift;
 178                    } else {
 179                      #warn scalar(@_). ": ". join(" / ", @_);
 180                      $param = { @_ };
 181                    }
 182
 183                    $param->{_packet} = \''. $autoload{$autoload}. '\';
 184
 185                    simple_packet($param);
 186                  }';
 187
 188   eval $eval;
 189   die $@ if $@;
 190
 191 }
 192
 193 sub simple_packet {
 194   my $packet = shift;
 195   warn "sending ". $packet->{_packet}. " to server"
 196     if $DEBUG;
 197   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
 198   connect(SOCK, sockaddr_un($socket)) or die "connect to $socket: $!";
 199   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
 200   SOCK->flush;
 201
 202   #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
 203
 204   #block until there is a message on socket
 205 #  my $w = new IO::Select;
 206 #  $w->add(\*SOCK);
 207 #  my @wait = $w->can_read;
 208
 209   warn "reading message from server"
 210     if $DEBUG;
 211
 212   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
 213   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
 214
 215   warn "returning message to client"
 216     if $DEBUG;
 217
 218   $return;
 219 }
 220
 221 =head1 NAME
 222
 223 FS::SelfService - Freeside self-service API
 224
 225 =head1 SYNOPSIS
 226
 227   # password and shell account changes
 228   use FS::SelfService qw(passwd chfn chsh);
 229
 230   # "my account" functionality
 231   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
 232
 233   #new-style login with an email address and password
 234   # can also be used for svc_acct login, set $emailaddress to username@domain
 235   my $rv = login ( { 'email'    => $emailaddress,
 236                      'password' => $password,
 237                    },
 238                  );
 239   if ( $rv->{'error'} ) {
 240     #handle login error...
 241   } else {
 242     #successful login
 243     $session_id = $rv->{'session_id'};
 244   }
 245
 246   #classic svc_acct-based login with separate username and password
 247   my $rv = login( { 'username' => $username,
 248                     'domain'   => $domain,
 249                     'password' => $password,
 250                   }
 251                 );
 252   if ( $rv->{'error'} ) {
 253     #handle login error...
 254   } else {
 255     #successful login
 256     $session_id = $rv->{'session_id'};
 257   }
 258
 259   #svc_phone login with phone number and PIN
 260   my $rv = login( { 'username' => $phone_number,
 261                     'domain'   => 'svc_phone',
 262                     'password' => $pin,
 263                   }
 264                 );
 265   if ( $rv->{'error'} ) {
 266     #handle login error...
 267   } else {
 268     #successful login
 269     $session_id = $rv->{'session_id'};
 270   }
 271
 272   my $customer_info = customer_info( { 'session_id' => $session_id } );
 273
 274   #payment_info and process_payment are available in 1.5+ only
 275   my $payment_info = payment_info( { 'session_id' => $session_id } );
 276
 277   #!!! process_payment example
 278
 279   #!!! list_pkgs example
 280
 281   #ordering a package with an svc_acct service
 282   my $rv = order_pkg( { 'session_id' => $session_id,
 283                         'pkgpart'    => $pkgpart,
 284                         'svcpart'    => $svcpart,
 285                         'username'   => $username,
 286                         'domsvc'     => $domsvc, #svcnum of svc_domain
 287                         '_password'  => $password,
 288                       }
 289                     );
 290
 291   #!!! ordering a package with an svc_domain service example
 292
 293   #!!! ordering a package with an svc_phone service example
 294
 295   #!!! ordering a package with an svc_external service example
 296
 297   #!!! ordering a package with an svc_pbx service
 298
 299   #ordering a package with no service
 300   my $rv = order_pkg( { 'session_id' => $session_id,
 301                         'pkgpart'    => $pkgpart,
 302                         'svcpart'    => 'none',
 303                       }
 304                     );
 305
 306   #quoting a package, then ordering after confirmation
 307
 308   my $rv = quotation_new({ 'session_id' => $session_id });
 309   my $qnum = $rv->{quotationnum};
 310   #  add packages to the quotation
 311   $rv = quotation_add_pkg({ 'session_id'   => $session_id,
 312                             'quotationnum' => $qnum,
 313                             'pkgpart'      => $pkgpart,
 314                             'quantity'     => $quantity, # defaults to 1
 315                           });
 316   #  repeat until all packages are added
 317   #  view the pricing information
 318   $rv = quotation_info({ 'session_id'   => $session_id,
 319                          'quotationnum' => $qnum,
 320                       });
 321   print "Total setup charges: ".$rv->{total_setup}."\n".
 322         "Total recurring charges: ".$rv->{total_recur}."\n";
 323   #  quotation_info also provides a detailed breakdown of charges, in
 324   #  $rv->{sections}.
 325
 326   #  ask customer for confirmation, then:
 327   $rv = quotation_order({ 'session_id'   => $session_id,
 328                           'quotationnum' => $qnum,
 329                         });
 330
 331   #!!! cancel_pkg example
 332
 333   # signup functionality
 334   use FS::SelfService qw( signup_info new_customer new_customer_minimal );
 335
 336   my $signup_info = signup_info;
 337
 338   $rv = new_customer( {
 339                         'first'            => $first,
 340                         'last'             => $last,
 341                         'company'          => $company,
 342                         'address1'         => $address1,
 343                         'address2'         => $address2,
 344                         'city'             => $city,
 345                         'state'            => $state,
 346                         'zip'              => $zip,
 347                         'country'          => $country,
 348                         'daytime'          => $daytime,
 349                         'night'            => $night,
 350                         'fax'              => $fax,
 351                         'payby'            => $payby,
 352                         'payinfo'          => $payinfo,
 353                         'paycvv'           => $paycvv,
 354                         'paystart_month'   => $paystart_month
 355                         'paystart_year'    => $paystart_year,
 356                         'payissue'         => $payissue,
 357                         'payip'            => $payip
 358                         'paydate'          => $paydate,
 359                         'payname'          => $payname,
 360                         'invoicing_list'   => $invoicing_list,
 361                         'referral_custnum' => $referral_custnum,
 362                         'agentnum'         => $agentnum,
 363                         'pkgpart'          => $pkgpart,
 364
 365                         'username'         => $username,
 366                         '_password'        => $password,
 367                         'popnum'           => $popnum,
 368                         #OR
 369                         'countrycode'      => 1,
 370                         'phonenum'         => $phonenum,
 371                         'pin'              => $pin,
 372                       }
 373                     );
 374
 375   my $error = $rv->{'error'};
 376   if ( $error eq '_decline' ) {
 377     print_decline();
 378   } elsif ( $error ) {
 379     reprint_signup();
 380   } else {
 381     print_success();
 382   }
 383
 384 =head1 DESCRIPTION
 385
 386 Use this API to implement your own client "self-service" module.
 387
 388 If you just want to customize the look of the existing "self-service" module,
 389 see XXXX instead.
 390
 391 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 392
 393 =over 4
 394
 395 =item passwd
 396
 397 Changes the password for an existing user in svc_acct.  Takes a hash
 398 reference with the following keys:
 399
 400 =over 4
 401
 402 =item username
 403
 404 Username of the account (required)
 405
 406 =item domain
 407
 408 Domain of the account (required)
 409
 410 =item old_password
 411
 412 Old password (required)
 413
 414 =item new_password
 415
 416 New password (required)
 417
 418 =item new_gecos
 419
 420 New gecos
 421
 422 =item new_shell
 423
 424 New Shell
 425
 426 =back
 427
 428 =item chfn
 429
 430 =item chsh
 431
 432 =back
 433
 434 =head1 "MY ACCOUNT" FUNCTIONS
 435
 436 =over 4
 437
 438 =item login HASHREF
 439
 440 Creates a user session.  Takes a hash reference as parameter with the
 441 following keys:
 442
 443 =over 4
 444
 445 =item email
 446
 447 Email address (username@domain), instead of username and domain.  Required for
 448 contact-based self-service login, can also be used for svc_acct-based login.
 449
 450 =item username
 451
 452 Username
 453
 454 =item domain
 455
 456 Domain
 457
 458 =item password
 459
 460 Password
 461
 462 =back
 463
 464 Returns a hash reference with the following keys:
 465
 466 =over 4
 467
 468 =item error
 469
 470 Empty on success, or an error message on errors.
 471
 472 =item session_id
 473
 474 Session identifier for successful logins
 475
 476 =back
 477
 478 =item customer_info HASHREF
 479
 480 Returns general customer information.
 481
 482 Takes a hash reference as parameter with a single key: B<session_id>
 483
 484 Returns a hash reference with the following keys:
 485
 486 =over 4
 487
 488 =item name
 489
 490 Customer name
 491
 492 =item balance
 493
 494 Balance owed
 495
 496 =item open
 497
 498 Array reference of hash references of open inoices.  Each hash reference has
 499 the following keys: invnum, date, owed
 500
 501 =item small_custview
 502
 503 An HTML fragment containing shipping and billing addresses.
 504
 505 =item The following fields are also returned
 506
 507 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
 508
 509 =back
 510
 511 =item customer_recurring HASHREF
 512
 513 Takes a hash reference as parameter with a single key B<session_id>
 514 or keys B<agent_session_id> and B<custnum>.
 515
 516 Returns a hash reference with the keys error, custnum and display_recurring.
 517
 518 display_recurring is an arrayref of hashrefs with the following keys:
 519
 520 =over 4
 521
 522 =item freq
 523
 524 frequency of charge, in months unless units are specified
 525
 526 =item freq_pretty
 527
 528 frequency of charge, suitable for display
 529
 530 =item amount
 531
 532 amount charged at this frequency
 533
 534 =back
 535
 536 =item edit_info HASHREF
 537
 538 Takes a hash reference as parameter with any of the following keys:
 539
 540 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
 541
 542 If a field exists, the customer record is updated with the new value of that
 543 field.  If a field does not exist, that field is not changed on the customer
 544 record.
 545
 546 Returns a hash reference with a single key, B<error>, empty on success, or an
 547 error message on errors
 548
 549 =item invoice HASHREF
 550
 551 Returns an invoice.  Takes a hash reference as parameter with two keys:
 552 session_id and invnum
 553
 554 Returns a hash reference with the following keys:
 555
 556 =over 4
 557
 558 =item error
 559
 560 Empty on success, or an error message on errors
 561
 562 =item invnum
 563
 564 Invoice number
 565
 566 =item invoice_text
 567
 568 Invoice text
 569
 570 =back
 571
 572 =item list_invoices HASHREF
 573
 574 Returns a list of all customer invoices.  Takes a hash reference with a single
 575 key, session_id.
 576
 577 Returns a hash reference with the following keys:
 578
 579 =over 4
 580
 581 =item error
 582
 583 Empty on success, or an error message on errors
 584
 585 =item invoices
 586
 587 Reference to array of hash references with the following keys:
 588
 589 =over 4
 590
 591 =item invnum
 592
 593 Invoice ID
 594
 595 =item _date
 596
 597 Invoice date, in UNIX epoch time
 598
 599 =back
 600
 601 =back
 602
 603 =item list_payby HASHREF
 604
 605 Returns a list of all stored customer payment information (credit cards and
 606 electronic check accounts).  Takes a hash reference with a single key,
 607 session_id.
 608
 609 Returns a hash reference with the following keys:
 610
 611 =over 4
 612
 613 =item error
 614
 615 Empty on success, or an error message on errors
 616
 617 =item payby
 618
 619 Reference to array of hash references with the following keys:
 620
 621 =over 4
 622
 623 =item custpaybynum
 624
 625 =item weight
 626
 627 Numeric weighting.  Stored payment information with a lower weight is attempted
 628 first.
 629
 630 =item payby
 631
 632 CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD
 633 (on-demand credit card) or DCHK (on-demand electronic check).
 634
 635 =item paymask
 636
 637 Masked credit card number (or, masked account and routing numbers)
 638
 639 =item paydate
 640
 641 Credit card expiration date
 642
 643 =item payname
 644
 645 Exact name on card (or bank name, for electronic checks)
 646
 647 =item paystate
 648
 649 For electronic checks, bank state
 650
 651 =item paytype
 652
 653 For electronic checks, account type (Personal/Business, Checking/Savings)
 654
 655 =back
 656
 657 =back
 658
 659 =item insert_payby HASHREF
 660
 661 Adds new stored payment information for this customer.  Takes a hash reference
 662 with the following keys:
 663
 664 =over 4
 665
 666 =item session_id
 667
 668 =item weight
 669
 670 Numeric weighting.  Stored payment information with a lower weight is attempted
 671 first.
 672
 673 =item payby
 674
 675 CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD
 676 (on-demand credit card) or DCHK (on-demand electronic check).
 677
 678 =item payinfo
 679
 680 Credit card number (or electronic check "account@routing")
 681
 682 =item paycvv
 683
 684 CVV2 number / security code
 685
 686 =item paydate
 687
 688 Credit card expiration date
 689
 690 =item payname
 691
 692 Exact name on card (or bank name, for electronic checks)
 693
 694 =item paystate
 695
 696 For electronic checks, bank state
 697
 698 =item paytype
 699
 700 For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
 701
 702 =item payip
 703
 704 Optional IP address from which payment was submitted
 705
 706 =back
 707
 708 If there is an error, returns a hash reference with a single key, B<error>,
 709 otherwise returns a hash reference with a single key, B<custpaybynum>.
 710
 711 =item update_payby HASHREF
 712
 713 Updates stored payment information.  Takes a hash reference with the same
 714 keys as insert_payby, as well as B<custpaybynum> to specify which record
 715 to update.  All keys except B<session_id> and B<custpaybynum> are optional;
 716 if omitted, the previous values in the record will be preserved.
 717
 718 If there is an error, returns a hash reference with a single key, B<error>,
 719 otherwise returns a hash reference with a single key, B<custpaybynum>.
 720
 721 =item delete_payby HASHREF
 722
 723 Removes stored payment information.  Takes a hash reference with two keys,
 724 B<session_id> and B<custpaybynum>.  Returns a hash reference with a single key,
 725 B<error>, which is an error message or empty for successful removal.
 726
 727 =item cancel HASHREF
 728
 729 Cancels this customer.
 730
 731 Takes a hash reference as parameter with a single key: B<session_id>
 732
 733 Returns a hash reference with a single key, B<error>, which is empty on
 734 success or an error message on errors.
 735
 736 =item payment_info HASHREF
 737
 738 Returns information that may be useful in displaying a payment page.
 739
 740 Takes a hash reference as parameter with a single key: B<session_id>.
 741
 742 Returns a hash reference with the following keys:
 743
 744 =over 4
 745
 746 =item error
 747
 748 Empty on success, or an error message on errors
 749
 750 =item balance
 751
 752 Balance owed
 753
 754 =item payname
 755
 756 Exact name on credit card (CARD/DCRD)
 757
 758 =item address1
 759
 760 Address line one
 761
 762 =item address2
 763
 764 Address line two
 765
 766 =item city
 767
 768 City
 769
 770 =item state
 771
 772 State
 773
 774 =item zip
 775
 776 Zip or postal code
 777
 778 =item payby
 779
 780 Customer's current default payment type.
 781
 782 =item card_type
 783
 784 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 785
 786 =item payinfo
 787
 788 For CARD/DCRD payment types, the card number
 789
 790 =item month
 791
 792 For CARD/DCRD payment types, expiration month
 793
 794 =item year
 795
 796 For CARD/DCRD payment types, expiration year
 797
 798 =item cust_main_county
 799
 800 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.
 801
 802 =item states
 803
 804 Array reference of all states in the current default country.
 805
 806 =item card_types
 807
 808 Hash reference of card types; keys are card types, values are the exact strings
 809 passed to the process_payment function
 810
 811 =cut
 812
 813 #this doesn't actually work yet
 814 #
 815 #=item paybatch
 816 #
 817 #Unique transaction identifier (prevents multiple charges), passed to the
 818 #process_payment function
 819
 820 =back
 821
 822 =item process_payment HASHREF
 823
 824 Processes a payment and possible change of address or payment type.  Takes a
 825 hash reference as parameter with the following keys:
 826
 827 =over 4
 828
 829 =item session_id
 830
 831 Session identifier
 832
 833 =item amount
 834
 835 Amount
 836
 837 =item save
 838
 839 If true, address and card information entered will be saved for subsequent
 840 transactions.
 841
 842 =item auto
 843
 844 If true, future credit card payments will be done automatically (sets payby to
 845 CARD).  If false, future credit card payments will be done on-demand (sets
 846 payby to DCRD).  This option only has meaning if B<save> is set true.
 847
 848 =item payname
 849
 850 Name on card
 851
 852 =item address1
 853
 854 Address line one
 855
 856 =item address2
 857
 858 Address line two
 859
 860 =item city
 861
 862 City
 863
 864 =item state
 865
 866 State
 867
 868 =item zip
 869
 870 Zip or postal code
 871
 872 =item country
 873
 874 Two-letter country code
 875
 876 =item payinfo
 877
 878 Card number
 879
 880 =item month
 881
 882 Card expiration month
 883
 884 =item year
 885
 886 Card expiration year
 887
 888 =cut
 889
 890 #this doesn't actually work yet
 891 #
 892 #=item paybatch
 893 #
 894 #Unique transaction identifier, returned from the payment_info function.
 895 #Prevents multiple charges.
 896
 897 =back
 898
 899 Returns a hash reference with a single key, B<error>, empty on success, or an
 900 error message on errors.
 901
 902 =item process_payment_order_pkg
 903
 904 Combines the B<process_payment> and B<order_pkg> functions in one step.  If the
 905 payment processes sucessfully, the package is ordered.  Takes a hash reference
 906 as parameter with the keys of both methods.
 907
 908 Returns a hash reference with a single key, B<error>, empty on success, or an
 909 error message on errors.
 910
 911 =item process_payment_change_pkg
 912
 913 Combines the B<process_payment> and B<change_pkg> functions in one step.  If the
 914 payment processes sucessfully, the package is ordered.  Takes a hash reference
 915 as parameter with the keys of both methods.
 916
 917 Returns a hash reference with a single key, B<error>, empty on success, or an
 918 error message on errors.
 919
 920
 921 =item process_payment_order_renew
 922
 923 Combines the B<process_payment> and B<order_renew> functions in one step.  If
 924 the payment processes sucessfully, the renewal is processed.  Takes a hash
 925 reference as parameter with the keys of both methods.
 926
 927 Returns a hash reference with a single key, B<error>, empty on success, or an
 928 error message on errors.
 929
 930 =item list_pkgs
 931
 932 Returns package information for this customer.  For more detail on services,
 933 see L</list_svcs>.
 934
 935 Takes a hash reference as parameter with a single key: B<session_id>
 936
 937 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 938
 939 =over 4
 940
 941 =item custnum
 942
 943 Customer number
 944
 945 =item error
 946
 947 Empty on success, or an error message on errors.
 948
 949 =item cust_pkg HASHREF
 950
 951 Array reference of hash references, each of which has the fields of a cust_pkg
 952 record (see L<FS::cust_pkg>) as well as the fields below.  Note these are not
 953 the internal FS:: objects, but hash references of columns and values.
 954
 955 =over 4
 956
 957 =item part_pkg fields
 958
 959 All fields of part_pkg for this specific cust_pkg (be careful with this
 960 information - it may reveal more about your available packages than you would
 961 like users to know in aggregate)
 962
 963 =cut
 964
 965 #XXX pare part_pkg fields down to a more secure subset
 966
 967 =item part_svc
 968
 969 An array of hash references indicating information on unprovisioned services
 970 available for provisioning for this specific cust_pkg.  Each has the following
 971 keys:
 972
 973 =over 4
 974
 975 =item part_svc fields
 976
 977 All fields of part_svc (be careful with this information - it may reveal more
 978 about your available packages than you would like users to know in aggregate)
 979
 980 =cut
 981
 982 #XXX pare part_svc fields down to a more secure subset
 983
 984 =back
 985
 986 =item cust_svc
 987
 988 An array of hash references indicating information on the customer services
 989 already provisioned for this specific cust_pkg.  Each has the following keys:
 990
 991 =over 4
 992
 993 =item label
 994
 995 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.
 996
 997 =back
 998
 999 =item svcnum
1000
1001 Primary key for this service
1002
1003 =item svcpart
1004
1005 Service definition (see L<FS::part_svc>)
1006
1007 =item pkgnum
1008
1009 Customer package (see L<FS::cust_pkg>)
1010
1011 =item overlimit
1012
1013 Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).
1014
1015 =back
1016
1017 =back
1018
1019 =item list_svcs
1020
1021 Returns service information for this customer.
1022
1023 Takes a hash reference as parameter with a single key: B<session_id>
1024
1025 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
1026
1027 =over 4
1028
1029 =item custnum
1030
1031 Customer number
1032
1033 =item svcs
1034
1035 An array of hash references indicating information on all of this customer's
1036 services.  Each has the following keys:
1037
1038 =over 4
1039
1040 =item svcnum
1041
1042 Primary key for this service
1043
1044 =item label
1045
1046 Name of this service
1047
1048 =item value
1049
1050 Meaningful user-specific identifier for the service (i.e. username, domain, or
1051 mail alias).
1052
1053 =back
1054
1055 Account (svc_acct) services also have the following keys:
1056
1057 =over 4
1058
1059 =item username
1060
1061 Username
1062
1063 =item email
1064
1065 username@domain
1066
1067 =item seconds
1068
1069 Seconds remaining
1070
1071 =item upbytes
1072
1073 Upload bytes remaining
1074
1075 =item downbytes
1076
1077 Download bytes remaining
1078
1079 =item totalbytes
1080
1081 Total bytes remaining
1082
1083 =item recharge_amount
1084
1085 Cost of a recharge
1086
1087 =item recharge_seconds
1088
1089 Number of seconds gained by recharge
1090
1091 =item recharge_upbytes
1092
1093 Number of upload bytes gained by recharge
1094
1095 =item recharge_downbytes
1096
1097 Number of download bytes gained by recharge
1098
1099 =item recharge_totalbytes
1100
1101 Number of total bytes gained by recharge
1102
1103 =back
1104
1105 =back
1106
1107 =item order_pkg
1108
1109 Orders a package for this customer.
1110
1111 If signup_server-realtime is set, bills the new package, attemps to collect
1112 payment and (for auto-payment customers) cancels the package if the payment is
1113 declined.
1114
1115 Takes a hash reference as parameter with the following keys:
1116
1117 =over 4
1118
1119 =item session_id
1120
1121 Session identifier
1122
1123 =item pkgpart
1124
1125 Package to order (see L<FS::part_pkg>).
1126
1127 =item quantity
1128
1129 Quantity for this package order (default 1).
1130
1131 =item run_bill_events
1132
1133 If true, runs billing events for the customer after ordering and billing the
1134 package (signup_server-realtime must be set).
1135
1136 =item locationnum
1137
1138 Optional locationnum for this package order, for existing locations.
1139
1140 Or, for new locations, pass the following fields: address1*, address2, city*,
1141 county, state*, zip*, country.  (* = required in this case)
1142
1143 (None of this is required at all if you are just ordering a package
1144 at the customer's existing default service location.)
1145
1146 =item address1
1147
1148 =item address2
1149
1150 =item city
1151
1152 =item county
1153
1154 =item state
1155
1156 =item zip
1157
1158 =item country
1159
1160 =item svcpart
1161
1162 Service to order (see L<FS::part_svc>).
1163
1164 Normally optional; required only to provision a non-svc_acct service, or if the
1165 package definition does not contain one svc_acct service definition with
1166 quantity 1 (it may contain others with quantity >1).  A svcpart of "none" can
1167 also be specified to indicate that no initial service should be provisioned.
1168
1169 =back
1170
1171 Fields used when provisioning an svc_acct service:
1172
1173 =over 4
1174
1175 =item username
1176
1177 Username
1178
1179 =item _password
1180
1181 Password
1182
1183 =item sec_phrase
1184
1185 Optional security phrase
1186
1187 =item popnum
1188
1189 Optional Access number number
1190
1191 =back
1192
1193 Fields used when provisioning an svc_domain service:
1194
1195 =over 4
1196
1197 =item domain
1198
1199 Domain
1200
1201 =back
1202
1203 Fields used when provisioning an svc_phone service:
1204
1205 =over 4
1206
1207 =item phonenum
1208
1209 Phone number
1210
1211 =item pin
1212
1213 Voicemail PIN
1214
1215 =item sip_password
1216
1217 SIP password
1218
1219 =back
1220
1221 Fields used when provisioning an svc_external service:
1222
1223 =over 4
1224
1225 =item id
1226
1227 External numeric ID.
1228
1229 =item title
1230
1231 External text title.
1232
1233 =back
1234
1235 Fields used when provisioning an svc_pbx service:
1236
1237 =over 4
1238
1239 =item id
1240
1241 Numeric ID.
1242
1243 =item name
1244
1245 Text name.
1246
1247 =back
1248
1249 Returns a hash reference with a single key, B<error>, empty on success, or an
1250 error message on errors.  The special error '_decline' is returned for
1251 declined transactions.
1252
1253 =item change_pkg
1254
1255 Changes a package for this customer.
1256
1257 Takes a hash reference as parameter with the following keys:
1258
1259 =over 4
1260
1261 =item session_id
1262
1263 Session identifier
1264
1265 =item pkgnum
1266
1267 Existing customer package.
1268
1269 =item pkgpart
1270
1271 New package to order (see L<FS::part_pkg>).
1272
1273 =item quantity
1274
1275 Quantity for this package order (default 1).
1276
1277 =back
1278
1279 Returns a hash reference with the following keys:
1280
1281 =over 4
1282
1283 =item error
1284
1285 Empty on success, or an error message on errors.
1286
1287 =item pkgnum
1288
1289 On success, the new pkgnum
1290
1291 =back
1292
1293
1294 =item renew_info
1295
1296 Provides useful info for early renewals.
1297
1298 Takes a hash reference as parameter with the following keys:
1299
1300 =over 4
1301
1302 =item session_id
1303
1304 Session identifier
1305
1306 =back
1307
1308 Returns a hash reference.  On errors, it contains a single key, B<error>, with
1309 the error message.  Otherwise, contains a single key, B<dates>, pointing to
1310 an array refernce of hash references.  Each hash reference contains the
1311 following keys:
1312
1313 =over 4
1314
1315 =item bill_date
1316
1317 (Future) Bill date.  Indicates a future date for which billing could be run.
1318 Specified as an integer UNIX timestamp.  Pass this value to the B<order_renew>
1319 function.
1320
1321 =item bill_date_pretty
1322
1323 (Future) Bill date as a human-readable string.  (Convenience for display;
1324 subject to change, so best not to parse for the date.)
1325
1326 =item amount
1327
1328 Base amount which will be charged if renewed early as of this date.
1329
1330 =item renew_date
1331
1332 Renewal date; i.e. even-futher future date at which the customer will be paid
1333 through if the early renewal is completed with the given B<bill-date>.
1334 Specified as an integer UNIX timestamp.
1335
1336 =item renew_date_pretty
1337
1338 Renewal date as a human-readable string.  (Convenience for display;
1339 subject to change, so best not to parse for the date.)
1340
1341 =item pkgnum
1342
1343 Package that will be renewed.
1344
1345 =item expire_date
1346
1347 Expiration date of the package that will be renewed.
1348
1349 =item expire_date_pretty
1350
1351 Expiration date of the package that will be renewed, as a human-readable
1352 string.  (Convenience for display; subject to change, so best not to parse for
1353 the date.)
1354
1355 =back
1356
1357 =item order_renew
1358
1359 Renews this customer early; i.e. runs billing for this customer in advance.
1360
1361 Takes a hash reference as parameter with the following keys:
1362
1363 =over 4
1364
1365 =item session_id
1366
1367 Session identifier
1368
1369 =item date
1370
1371 Integer date as returned by the B<renew_info> function, indicating the advance
1372 date for which to run billing.
1373
1374 =back
1375
1376 Returns a hash reference with a single key, B<error>, empty on success, or an
1377 error message on errors.
1378
1379 =item cancel_pkg
1380
1381 Cancels a package for this customer.
1382
1383 Takes a hash reference as parameter with the following keys:
1384
1385 =over 4
1386
1387 =item session_id
1388
1389 Session identifier
1390
1391 =item pkgpart
1392
1393 pkgpart of package to cancel
1394
1395 =item date
1396
1397 Optional date, for future cancellation (expiration) instead of immediate
1398 cancellation.  Specified as an integer UNIX timestamp ("epoch time").
1399
1400 =back
1401
1402 Returns a hash reference with a single key, B<error>, empty on success, or an
1403 error message on errors.
1404
1405 =item provision_acct
1406
1407 Provisions an account (svc_acct).
1408
1409 Takes a hash reference as parameter with the following keys:
1410
1411 =over 4
1412
1413 =item session_id
1414
1415 Session identifier
1416
1417 =item pkgnum
1418
1419 pkgnum of package into which this service is provisioned
1420
1421 =item svcpart
1422
1423 svcpart or service definition to provision
1424
1425 =item username
1426
1427 =item domsvc
1428
1429 =item _password
1430
1431 =back
1432
1433 =item provision_phone
1434
1435 Provisions a phone number (svc_phone).
1436
1437 Takes a hash reference as parameter with the following keys:
1438
1439 =over 4
1440
1441 =item session_id
1442
1443 Session identifier
1444
1445 =item pkgnum
1446
1447 pkgnum of package into which this service is provisioned
1448
1449 =item svcpart
1450
1451 svcpart or service definition to provision
1452
1453 =item countrycode
1454
1455 =item phonenum
1456
1457 =item address1
1458
1459 =item address2
1460
1461 =item city
1462
1463 =item county
1464
1465 =item state
1466
1467 =item zip
1468
1469 =item country
1470
1471 E911 Address (optional)
1472
1473 =back
1474
1475 =item provision_pbx
1476
1477 Provisions a customer PBX (svc_pbx).
1478
1479 Takes a hash reference as parameter with the following keys:
1480
1481 =over 4
1482
1483 =item session_id
1484
1485 Session identifier
1486
1487 =item pkgnum
1488
1489 pkgnum of package into which this service is provisioned
1490
1491 =item svcpart
1492
1493 svcpart or service definition to provision
1494
1495 =item id
1496
1497 =item title
1498
1499 =item max_extensions
1500
1501 =item max_simultaneous
1502
1503 =item ip_addr
1504
1505 =back
1506
1507 =item provision_external
1508
1509 Provisions an external service (svc_external).
1510
1511 Takes a hash reference as parameter with the following keys:
1512
1513 =over 4
1514
1515 =item session_id
1516
1517 Session identifier
1518
1519 =item pkgnum
1520
1521 pkgnum of package into which this service is provisioned
1522
1523 =item svcpart
1524
1525 svcpart or service definition to provision
1526
1527 =item id
1528
1529 =item title
1530
1531 =back
1532
1533 =back
1534
1535 =head2 "MY ACCOUNT" CONTACT FUNCTIONS
1536
1537 =over 4
1538
1539 =item contact_passwd
1540
1541 Changes the password for the currently-logged in contact.
1542
1543 Takes a hash reference as parameter with the following keys:
1544
1545 =over 4
1546
1547 =item session_id
1548
1549 =item new_password
1550
1551 =back
1552
1553 Returns a hash reference with a single parameter, B<error>, which contains an
1554 error message, or empty on success.
1555
1556 =item list_contacts
1557
1558 Takes a hash reference as parameter with a single key, B<session_id>.
1559
1560 Returns a hash reference with two parameters: B<error>, which contains an error
1561 message, or empty on success, and B<contacts>, a list of contacts.
1562
1563 B<contacts> is an array reference of hash references (i.e. an array of structs,
1564  in XML-RPC).  Each hash reference (struct) has the following keys:
1565
1566 =over 4
1567
1568 =item contactnum
1569
1570 =item class
1571
1572 Contact class name (contact type).
1573
1574 =item first
1575
1576 First name
1577
1578 =item last
1579
1580 Last name
1581
1582 =item title
1583
1584 Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
1585
1586 =item emailaddress
1587
1588 Comma-separated list of email addresses
1589
1590 =item comment
1591
1592 =item selfservice_access
1593
1594 Y when enabled
1595
1596 =back
1597
1598 =item edit_contact
1599
1600 Updates information for the currently-logged in contact, or (optionally) the
1601 specified contact.
1602
1603 Takes a hash reference as parameter with the following keys:
1604
1605 =over 4
1606
1607 =item session_id
1608
1609 =item contactnum
1610
1611 If already logged in as a contact, this is optional.
1612
1613 =item first
1614
1615 =item last
1616
1617 =item emailaddress
1618
1619 =back
1620
1621 Returns a hash reference with a single parameter, B<error>, which contains an
1622 error message, or empty on success.
1623
1624 =item new_contact
1625
1626 Creates a new contact.
1627
1628 Takes a hash reference as parameter with the following keys:
1629
1630 =over 4
1631
1632 =item session_id
1633
1634 =item first
1635
1636 =item last
1637
1638 =item emailaddress
1639
1640 =item classnum
1641
1642 Optional contact classnum (TODO: or name)
1643
1644 =item comment
1645
1646 =item selfservice_access
1647
1648 Y to enable self-service access
1649
1650 =item _password
1651
1652 =back
1653
1654 Returns a hash reference with a single parameter, B<error>, which contains an
1655 error message, or empty on success.
1656
1657 =item delete_contact
1658
1659 Deletes a contact.  (Note: Cannot at this time delete the currently-logged in
1660 contact.)
1661
1662 Takes a hash reference as parameter with the following keys:
1663
1664 =over 4
1665
1666 =item session_id
1667
1668 =item contactnum
1669
1670 =back
1671
1672 Returns a hash reference with a single parameter, B<error>, which contains an
1673 error message, or empty on success.
1674
1675 =back
1676
1677 =head2 "MY ACCOUNT" QUOTATION FUNCTIONS
1678
1679 All of these functions require the user to be logged in, and the 'session_id'
1680 key to be included in the argument hashref.`
1681
1682 =over 4
1683
1684 =item list_quotations HASHREF
1685
1686 Returns a hashref listing this customer's active self-service quotations.
1687 Contents are:
1688
1689 =over 4
1690
1691 =item quotations
1692
1693 an arrayref containing an element for each quotation.
1694
1695 =item quotationnum
1696
1697 the primary key
1698
1699 =item _date
1700
1701 the date it was started
1702
1703 =item num_pkgs
1704
1705 the number of packages
1706
1707 =item total_setup
1708
1709 the sum of setup fees
1710
1711 =item total_recur
1712
1713 the sum of recurring charges
1714
1715 =back
1716
1717 =item quotation_new HASHREF
1718
1719 Creates an empty quotation and returns a hashref containing 'quotationnum',
1720 the primary key of the new quotation.
1721
1722 =item quotation_delete HASHREF
1723
1724 Disables (does not really delete) a quotation. Takes the following arguments:
1725
1726 =over 4
1727
1728 =item session_id
1729
1730 =item quotationnum - the quotation to delete
1731
1732 =back
1733
1734 Returns 'error' => a string, which will be empty on success.
1735
1736 =item quotation_info HASHREF
1737
1738 Returns total and detailed pricing information on a quotation.
1739
1740 Takes the following arguments:
1741
1742 =over 4
1743
1744 =item session_id
1745
1746 =item quotationnum - the quotation to return
1747
1748 =back
1749
1750 Returns a hashref containing:
1751
1752 - total_setup, the total of setup fees (and their taxes)
1753 - total_recur, the total of all recurring charges (and their taxes)
1754 - sections, an arrayref containing an element for each quotation section.
1755   - description, a line of text describing the group of charges
1756   - subtotal, the total of charges in this group (if appropriate)
1757   - detail_items, an arrayref of line items
1758     - pkgnum, the reference number of the package
1759     - description, the package name (or tax name)
1760     - quantity
1761     - amount, the amount charged
1762     If the detail item represents a subtotal, it will instead contain:
1763     - total_item: description of the subtotal
1764     - total_amount: the subtotal amount
1765
1766
1767 =item quotation_print HASHREF
1768
1769 Renders the quotation as HTML or PDF. Takes the following arguments:
1770
1771 =over 4
1772
1773 =item session_id
1774
1775 =item quotationnum - the quotation to return
1776
1777 =item format - 'html' or 'pdf'
1778
1779 =back
1780
1781 Returns a hashref containing 'document', the contents of the file.
1782
1783 =item quotation_add_pkg HASHREF
1784
1785 Adds a package to a quotation. Takes the following arguments:
1786
1787 =over 4
1788
1789 =item session_id
1790
1791 =item pkgpart - the package to add
1792
1793 =item quotationnum - the quotation to add it to
1794
1795 =item quantity - the package quantity (defaults to 1)
1796
1797 =item address1, address2, city, state, zip, country - address fields to set
1798 the service location
1799
1800 =back
1801
1802 Returns 'error' => a string, which will be empty on success.
1803
1804 =item quotation_remove_pkg HASHREF
1805
1806 Removes a package from a quotation. Takes the following arguments:
1807
1808 =over 4
1809
1810 =item session_id
1811
1812 =item pkgnum - the primary key (quotationpkgnum) of the package to remove
1813
1814 =item quotationnum - the quotation to remove it from
1815
1816 =back
1817
1818 Returns 'error' => a string, which will be empty on success.
1819
1820 =item quotation_order HASHREF
1821
1822 Converts the packages in a quotation into real packages. Takes the following
1823 arguments:
1824
1825 Takes the following arguments:
1826
1827 =over 4
1828
1829 =item session_id
1830
1831 =item quotationnum - the quotation to order
1832
1833 =back
1834
1835 =back
1836
1837 =head1 SIGNUP FUNCTIONS
1838
1839 =over 4
1840
1841 =item signup_info HASHREF
1842
1843 Takes a hash reference as parameter with the following keys:
1844
1845 =over 4
1846
1847 =item session_id - Optional agent/reseller interface session
1848
1849 =back
1850
1851 Returns a hash reference containing information that may be useful in
1852 displaying a signup page.  The hash reference contains the following keys:
1853
1854 =over 4
1855
1856 =item cust_main_county
1857
1858 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.
1859
1860 =item part_pkg
1861
1862 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
1863 an agentnum specified explicitly via reseller interface session_id in the
1864 options.
1865
1866 =item agent
1867
1868 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.
1869
1870 =item agentnum2part_pkg
1871
1872 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.
1873
1874 =item svc_acct_pop
1875
1876 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.
1877
1878 =item security_phrase
1879
1880 True if the "security_phrase" feature is enabled
1881
1882 =item payby
1883
1884 Array reference of acceptable payment types for signup
1885
1886 =over 4
1887
1888 =item CARD
1889
1890 credit card - automatic
1891
1892 =item DCRD
1893
1894 credit card - on-demand - version 1.5+ only
1895
1896 =item CHEK
1897
1898 electronic check - automatic
1899
1900 =item DCHK
1901
1902 electronic check - on-demand - version 1.5+ only
1903
1904 =item LECB
1905
1906 Phone bill billing
1907
1908 =item BILL
1909
1910 billing, not recommended for signups
1911
1912 =item COMP
1913
1914 free, definitely not recommended for signups
1915
1916 =item PREPAY
1917
1918 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1919
1920 =back
1921
1922 =item cvv_enabled
1923
1924 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1925
1926 =item msgcat
1927
1928 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".
1929
1930 =item statedefault
1931
1932 Default state
1933
1934 =item countrydefault
1935
1936 Default country
1937
1938 =back
1939
1940 =item new_customer_minimal HASHREF
1941
1942 Creates a new customer.
1943
1944 Current differences from new_customer: An address is not required.  promo_code
1945 and reg_code are not supported.  If invoicing_list and _password is passed, a
1946 contact will be created with self-service access (no pkgpart or username is
1947 necessary).  No initial billing is run (this may change in a future version).
1948
1949 Takes a hash reference as parameter with the following keys:
1950
1951 =over 4
1952
1953 =item first
1954
1955 first name (required)
1956
1957 =item last
1958
1959 last name (required)
1960
1961 =item ss
1962
1963 (not typically collected; mostly used for ACH transactions)
1964
1965 =item company
1966
1967 Company name
1968
1969 =item address1
1970
1971 Address line one
1972
1973 =item address2
1974
1975 Address line two
1976
1977 =item city
1978
1979 City
1980
1981 =item county
1982
1983 County
1984
1985 =item state
1986
1987 State
1988
1989 =item zip
1990
1991 Zip or postal code
1992
1993 =item daytime
1994
1995 Daytime phone number
1996
1997 =item night
1998
1999 Evening phone number
2000
2001 =item fax
2002
2003 Fax number
2004
2005 =item payby
2006
2007 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
2008
2009 =item payinfo
2010
2011 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
2012
2013 =item paycvv
2014
2015 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
2016
2017 =item paydate
2018
2019 Expiration date for CARD/DCRD
2020
2021 =item payname
2022
2023 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
2024
2025 =item invoicing_list
2026
2027 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),
2028
2029 =item referral_custnum
2030
2031 referring customer number
2032
2033 =item agentnum
2034
2035 Agent number
2036
2037 =item pkgpart
2038
2039 pkgpart of initial package
2040
2041 =item username
2042
2043 Username
2044
2045 =item _password
2046
2047 Password
2048
2049 =item sec_phrase
2050
2051 Security phrase
2052
2053 =item popnum
2054
2055 Access number (index, not the literal number)
2056
2057 =item countrycode
2058
2059 Country code (to be provisioned as a service)
2060
2061 =item phonenum
2062
2063 Phone number (to be provisioned as a service)
2064
2065 =item pin
2066
2067 Voicemail PIN
2068
2069 =back
2070
2071 Returns a hash reference with the following keys:
2072
2073 =over 4
2074
2075 =item error
2076
2077 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)
2078
2079 =back
2080
2081 =item new_customer HASHREF
2082
2083 Creates a new customer.  Takes a hash reference as parameter with the
2084 following keys:
2085
2086 =over 4
2087
2088 =item first
2089
2090 first name (required)
2091
2092 =item last
2093
2094 last name (required)
2095
2096 =item ss
2097
2098 (not typically collected; mostly used for ACH transactions)
2099
2100 =item company
2101
2102 Company name
2103
2104 =item address1 (required)
2105
2106 Address line one
2107
2108 =item address2
2109
2110 Address line two
2111
2112 =item city (required)
2113
2114 City
2115
2116 =item county
2117
2118 County
2119
2120 =item state (required)
2121
2122 State
2123
2124 =item zip (required)
2125
2126 Zip or postal code
2127
2128 =item daytime
2129
2130 Daytime phone number
2131
2132 =item night
2133
2134 Evening phone number
2135
2136 =item fax
2137
2138 Fax number
2139
2140 =item payby
2141
2142 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
2143
2144 =item payinfo
2145
2146 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
2147
2148 =item paycvv
2149
2150 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
2151
2152 =item paydate
2153
2154 Expiration date for CARD/DCRD
2155
2156 =item payname
2157
2158 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
2159
2160 =item invoicing_list
2161
2162 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),
2163
2164 =item referral_custnum
2165
2166 referring customer number
2167
2168 =item agentnum
2169
2170 Agent number
2171
2172 =item pkgpart
2173
2174 pkgpart of initial package
2175
2176 =item username
2177
2178 Username
2179
2180 =item _password
2181
2182 Password
2183
2184 =item sec_phrase
2185
2186 Security phrase
2187
2188 =item popnum
2189
2190 Access number (index, not the literal number)
2191
2192 =item countrycode
2193
2194 Country code (to be provisioned as a service)
2195
2196 =item phonenum
2197
2198 Phone number (to be provisioned as a service)
2199
2200 =item pin
2201
2202 Voicemail PIN
2203
2204 =back
2205
2206 Returns a hash reference with the following keys:
2207
2208 =over 4
2209
2210 =item error
2211
2212 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)
2213
2214 =back
2215
2216 =item regionselector HASHREF | LIST
2217
2218 Takes as input a hashref or list of key/value pairs with the following keys:
2219
2220 =over 4
2221
2222 =item selected_county
2223
2224 Currently selected county
2225
2226 =item selected_state
2227
2228 Currently selected state
2229
2230 =item selected_country
2231
2232 Currently selected country
2233
2234 =item prefix
2235
2236 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2237
2238 =item onchange
2239
2240 Specify a javascript subroutine to call on changes
2241
2242 =item default_state
2243
2244 Default state
2245
2246 =item default_country
2247
2248 Default country
2249
2250 =item locales
2251
2252 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>.
2253
2254 =back
2255
2256 Returns a list consisting of three HTML fragments for county selection,
2257 state selection and country selection, respectively.
2258
2259 =cut
2260
2261 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
2262 sub regionselector {
2263   my $param;
2264   if ( ref($_[0]) ) {
2265     $param = shift;
2266   } else {
2267     $param = { @_ };
2268   }
2269   $param->{'selected_country'} ||= $param->{'default_country'};
2270   $param->{'selected_state'} ||= $param->{'default_state'};
2271
2272   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2273
2274   my $countyflag = 0;
2275
2276   my %cust_main_county;
2277
2278 #  unless ( @cust_main_county ) { #cache
2279     #@cust_main_county = qsearch('cust_main_county', {} );
2280     #foreach my $c ( @cust_main_county ) {
2281     foreach my $c ( @{ $param->{'locales'} } ) {
2282       #$countyflag=1 if $c->county;
2283       $countyflag=1 if $c->{county};
2284       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
2285       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
2286       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
2287     }
2288 #  }
2289   $countyflag=1 if $param->{selected_county};
2290
2291   my $script_html = <<END;
2292     <SCRIPT>
2293     function opt(what,value,text) {
2294       var optionName = new Option(text, value, false, false);
2295       var length = what.length;
2296       what.options[length] = optionName;
2297     }
2298     function ${prefix}country_changed(what) {
2299       country = what.options[what.selectedIndex].text;
2300       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
2301           what.form.${prefix}state.options[i] = null;
2302 END
2303       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
2304
2305   foreach my $country ( sort keys %cust_main_county ) {
2306     $script_html .= "\nif ( country == \"$country\" ) {\n";
2307     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2308       my $text = $state || '(n/a)';
2309       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
2310     }
2311     $script_html .= "}\n";
2312   }
2313
2314   $script_html .= <<END;
2315     }
2316     function ${prefix}state_changed(what) {
2317 END
2318
2319   if ( $countyflag ) {
2320     $script_html .= <<END;
2321       state = what.options[what.selectedIndex].text;
2322       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
2323       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
2324           what.form.${prefix}county.options[i] = null;
2325 END
2326
2327     foreach my $country ( sort keys %cust_main_county ) {
2328       $script_html .= "\nif ( country == \"$country\" ) {\n";
2329       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2330         $script_html .= "\nif ( state == \"$state\" ) {\n";
2331           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
2332           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
2333             my $text = $county || '(n/a)';
2334             $script_html .=
2335               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
2336           }
2337         $script_html .= "}\n";
2338       }
2339       $script_html .= "}\n";
2340     }
2341   }
2342
2343   $script_html .= <<END;
2344     }
2345     </SCRIPT>
2346 END
2347
2348   my $county_html = $script_html;
2349   if ( $countyflag ) {
2350     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
2351     foreach my $county (
2352       sort keys %{ $cust_main_county{$param->{'selected_country'}}{$param->{'selected_state'}} }
2353     ) {
2354       my $text = $county || '(n/a)';
2355       $county_html .= qq!<OPTION VALUE="$county"!.
2356                       ($county eq $param->{'selected_county'} ?
2357                         ' SELECTED>' :
2358                         '>'
2359                       ).
2360                       $text.
2361                       '</OPTION>';
2362     }
2363     $county_html .= '</SELECT>';
2364   } else {
2365     $county_html .=
2366       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
2367   }
2368
2369   my $state_html = qq!<SELECT NAME="${prefix}state" !.
2370                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
2371   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
2372     my $text = $state || '(n/a)';
2373     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
2374     $state_html .= "\n<OPTION $selected VALUE=\"$state\">$text</OPTION>"
2375   }
2376   $state_html .= '</SELECT>';
2377
2378   my $country_html = '';
2379   if ( scalar( keys %cust_main_county ) > 1 )  {
2380
2381     $country_html = qq(<SELECT NAME="${prefix}country" ).
2382                     qq(onChange="${prefix}country_changed(this); ).
2383                                  $param->{'onchange'}.
2384                                '"'.
2385                       '>';
2386     my $countrydefault = $param->{default_country} || 'US';
2387     foreach my $country (
2388       sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
2389         keys %cust_main_county
2390     ) {
2391       my $selected = $country eq $param->{'selected_country'}
2392                        ? ' SELECTED'
2393                        : '';
2394       $country_html .= "\n<OPTION $selected>$country</OPTION>"
2395     }
2396     $country_html .= '</SELECT>';
2397   } else {
2398
2399     $country_html = qq(<INPUT TYPE="hidden" NAME="${prefix}country" ).
2400                             ' VALUE="'. (keys %cust_main_county )[0]. '">';
2401
2402   }
2403
2404   ($county_html, $state_html, $country_html);
2405
2406 }
2407
2408 sub regionselector_hashref {
2409   my ($county_html, $state_html, $country_html) = regionselector(@_);
2410   {
2411     'county_html'  => $county_html,
2412     'state_html'   => $state_html,
2413     'country_html' => $country_html,
2414   };
2415 }
2416
2417 =item location_form HASHREF | LIST
2418
2419 Takes as input a hashref or list of key/value pairs with the following keys:
2420
2421 =over 4
2422
2423 =item session_id
2424
2425 Current customer session_id
2426
2427 =item no_asterisks
2428
2429 Omit red asterisks from required fields.
2430
2431 =item address1_label
2432
2433 Label for first address line.
2434
2435 =back
2436
2437 Returns an HTML fragment for a location form (address, city, state, zip,
2438 country)
2439
2440 =cut
2441
2442 sub location_form {
2443   my $param;
2444   if ( ref($_[0]) ) {
2445     $param = shift;
2446   } else {
2447     $param = { @_ };
2448   }
2449
2450   my $session_id = delete $param->{'session_id'};
2451
2452   my $rv = mason_comp( 'session_id' => $session_id,
2453                        'comp'       => '/elements/location.html',
2454                        'args'       => [ %$param ],
2455                      );
2456
2457   #hmm.
2458   $rv->{'error'} || $rv->{'output'};
2459
2460 }
2461
2462
2463 #=item expselect HASHREF | LIST
2464 #
2465 #Takes as input a hashref or list of key/value pairs with the following keys:
2466 #
2467 #=over 4
2468 #
2469 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2470 #
2471 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
2472 #
2473 #=back
2474
2475 =item expselect PREFIX [ DATE ]
2476
2477 Takes as input a unique prefix string and the current expiration date, in
2478 yyyy-mm-dd or m-d-yyyy format
2479
2480 Returns an HTML fragments for expiration date selection.
2481
2482 =cut
2483
2484 sub expselect {
2485   #my $param;
2486   #if ( ref($_[0]) ) {
2487   #  $param = shift;
2488   #} else {
2489   #  $param = { @_ };
2490   #my $prefix = $param->{'prefix'};
2491   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2492   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
2493   my $prefix = shift;
2494   my $date = scalar(@_) ? shift : '';
2495
2496   my( $m, $y ) = ( 0, 0 );
2497   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
2498     ( $m, $y ) = ( $2, $1 );
2499   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
2500     ( $m, $y ) = ( $1, $3 );
2501   }
2502   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
2503   for ( 1 .. 12 ) {
2504     $return .= qq!<OPTION VALUE="$_"!;
2505     $return .= " SELECTED" if $_ == $m;
2506     $return .= ">$_";
2507   }
2508   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
2509   my @t = localtime;
2510   my $thisYear = $t[5] + 1900;
2511   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
2512     $return .= qq!<OPTION VALUE="$_"!;
2513     $return .= " SELECTED" if $_ == $y;
2514     $return .= ">$_";
2515   }
2516   $return .= "</SELECT>";
2517
2518   $return;
2519 }
2520
2521 =item popselector HASHREF | LIST
2522
2523 Takes as input a hashref or list of key/value pairs with the following keys:
2524
2525 =over 4
2526
2527 =item popnum
2528
2529 Access number number
2530
2531 =item pops
2532
2533 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>.
2534
2535 =back
2536
2537 Returns an HTML fragment for access number selection.
2538
2539 =cut
2540
2541 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
2542 sub popselector {
2543   my $param;
2544   if ( ref($_[0]) ) {
2545     $param = shift;
2546   } else {
2547     $param = { @_ };
2548   }
2549   my $popnum = $param->{'popnum'};
2550   my $pops = $param->{'pops'};
2551
2552   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
2553   return $pops->[0]{city}. ', '. $pops->[0]{state}.
2554          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
2555          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
2556     if scalar(@$pops) == 1;
2557
2558   my %pop = ();
2559   my %popnum2pop = ();
2560   foreach (@$pops) {
2561     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
2562     $popnum2pop{$_->{popnum}} = $_;
2563   }
2564
2565   my $text = <<END;
2566     <SCRIPT>
2567     function opt(what,href,text) {
2568       var optionName = new Option(text, href, false, false)
2569       var length = what.length;
2570       what.options[length] = optionName;
2571     }
2572 END
2573
2574   my $init_popstate = $param->{'init_popstate'};
2575   if ( $init_popstate ) {
2576     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
2577              $init_popstate. '">';
2578   } else {
2579     $text .= <<END;
2580       function acstate_changed(what) {
2581         state = what.options[what.selectedIndex].text;
2582         what.form.popac.options.length = 0
2583         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
2584 END
2585   }
2586
2587   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
2588   foreach my $state ( sort { $a cmp $b } @states ) {
2589     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
2590
2591     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
2592       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
2593       if ($ac eq $param->{'popac'}) {
2594         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
2595       }
2596     }
2597     $text .= "}\n" unless $init_popstate;
2598   }
2599   $text .= "popac_changed(what.form.popac)}\n";
2600
2601   $text .= <<END;
2602   function popac_changed(what) {
2603     ac = what.options[what.selectedIndex].text;
2604     what.form.popnum.options.length = 0;
2605     what.form.popnum.options[0] = new Option("City", "-1", false, true);
2606
2607 END
2608
2609   foreach my $state ( @states ) {
2610     foreach my $popac ( keys %{ $pop{$state} } ) {
2611       $text .= "\nif ( ac == \"$popac\" ) {\n";
2612
2613       foreach my $pop ( @{$pop{$state}->{$popac}}) {
2614         my $o_popnum = $pop->{popnum};
2615         my $poptext =  $pop->{city}. ', '. $pop->{state}.
2616                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2617
2618         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
2619         if ($popnum == $o_popnum) {
2620           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
2621         }
2622       }
2623       $text .= "}\n";
2624     }
2625   }
2626
2627
2628   $text .= "}\n</SCRIPT>\n";
2629
2630   $param->{'acstate'} = '' unless defined($param->{'acstate'});
2631
2632   $text .=
2633     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
2634     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
2635   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
2636            ">$_" foreach sort { $a cmp $b } @states;
2637   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
2638
2639   $text .=
2640     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
2641     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
2642
2643   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
2644
2645
2646   #comment this block to disable initial list polulation
2647   my @initial_select = ();
2648   if ( scalar( @$pops ) > 100 ) {
2649     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
2650   } else {
2651     @initial_select = @$pops;
2652   }
2653   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
2654     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
2655              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
2656              $pop->{city}. ', '. $pop->{state}.
2657                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2658   }
2659
2660   $text .= qq!</SELECT></TD></TR></TABLE>!;
2661
2662   $text;
2663
2664 }
2665
2666 =item domainselector HASHREF | LIST
2667
2668 Takes as input a hashref or list of key/value pairs with the following keys:
2669
2670 =over 4
2671
2672 =item pkgnum
2673
2674 Package number
2675
2676 =item domsvc
2677
2678 Service number of the selected item.
2679
2680 =back
2681
2682 Returns an HTML fragment for domain selection.
2683
2684 =cut
2685
2686 sub domainselector {
2687   my $param;
2688   if ( ref($_[0]) ) {
2689     $param = shift;
2690   } else {
2691     $param = { @_ };
2692   }
2693   my $domsvc= $param->{'domsvc'};
2694   my $rv =
2695       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
2696   my $domains = $rv->{'domains'};
2697   $domsvc = $rv->{'domsvc'} unless $domsvc;
2698
2699   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
2700     unless scalar(keys %$domains);
2701
2702   if (scalar(keys %$domains) == 1) {
2703     my $key;
2704     foreach(keys %$domains) {
2705       $key = $_;
2706     }
2707     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
2708            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
2709   }
2710
2711   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em">!;
2712
2713   $text .= '<OPTION>(Choose Domain)' unless $domsvc;
2714
2715   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
2716     $text .= qq!<OPTION VALUE="!. $domain. '"'.
2717              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
2718              $domains->{$domain};
2719   }
2720
2721   $text .= qq!</SELECT></TD></TR>!;
2722
2723   $text;
2724
2725 }
2726
2727 =item didselector HASHREF | LIST
2728
2729 Takes as input a hashref or list of key/value pairs with the following keys:
2730
2731 =over 4
2732
2733 =item field
2734
2735 Field name for the returned HTML fragment.
2736
2737 =item svcpart
2738
2739 Service definition (see L<FS::part_svc>)
2740
2741 =back
2742
2743 Returns an HTML fragment for DID selection.
2744
2745 =cut
2746
2747 sub didselector {
2748   my $param;
2749   if ( ref($_[0]) ) {
2750     $param = shift;
2751   } else {
2752     $param = { @_ };
2753   }
2754
2755   my $rv = mason_comp( 'comp'=>'/elements/select-did.html',
2756                        'args'=>[ %$param ],
2757                      );
2758
2759   #hmm.
2760   $rv->{'error'} || $rv->{'output'};
2761
2762 }
2763
2764 =back
2765
2766 =head1 RESELLER FUNCTIONS
2767
2768 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
2769 with their active session, and the B<customer_info> and B<order_pkg> functions
2770 with their active session and an additional I<custnum> parameter.
2771
2772 For the most part, development of the reseller web interface has been
2773 superceded by agent-virtualized access to the backend.
2774
2775 =over 4
2776
2777 =item agent_login
2778
2779 Agent login
2780
2781 =item agent_info
2782
2783 Agent info
2784
2785 =item agent_list_customers
2786
2787 List agent's customers.
2788
2789 =back
2790
2791 =head1 BUGS
2792
2793 =head1 SEE ALSO
2794
2795 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
2796
2797 =cut
2798
2799 1;
2800