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