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 Takes a hash reference as parameter with the following keys:
1075
1076 =over 4
1077
1078 =item session_id
1079
1080 Session identifier
1081
1082 =item pkgpart
1083
1084 Package to order (see L<FS::part_pkg>).
1085
1086 =item quantity
1087
1088 Quantity for this package order (default 1).
1089
1090 =item locationnum
1091
1092 Optional locationnum for this package order, for existing locations.
1093
1094 Or, for new locations, pass the following fields: address1*, address2, city*,
1095 county, state*, zip*, country.  (* = required in this case)
1096
1097 (None of this is required at all if you are just ordering a package
1098 at the customer's existing default service location.)
1099
1100 =item address1
1101
1102 =item address2
1103
1104 =item city
1105
1106 =item county
1107
1108 =item state
1109
1110 =item zip
1111
1112 =item country
1113
1114 =item svcpart
1115
1116 Service to order (see L<FS::part_svc>).
1117
1118 Normally optional; required only to provision a non-svc_acct service, or if the
1119 package definition does not contain one svc_acct service definition with
1120 quantity 1 (it may contain others with quantity >1).  A svcpart of "none" can
1121 also be specified to indicate that no initial service should be provisioned.
1122
1123 =back
1124
1125 Fields used when provisioning an svc_acct service:
1126
1127 =over 4
1128
1129 =item username
1130
1131 Username
1132
1133 =item _password
1134
1135 Password
1136
1137 =item sec_phrase
1138
1139 Optional security phrase
1140
1141 =item popnum
1142
1143 Optional Access number number
1144
1145 =back
1146
1147 Fields used when provisioning an svc_domain service:
1148
1149 =over 4
1150
1151 =item domain
1152
1153 Domain
1154
1155 =back
1156
1157 Fields used when provisioning an svc_phone service:
1158
1159 =over 4
1160
1161 =item phonenum
1162
1163 Phone number
1164
1165 =item pin
1166
1167 Voicemail PIN
1168
1169 =item sip_password
1170
1171 SIP password
1172
1173 =back
1174
1175 Fields used when provisioning an svc_external service:
1176
1177 =over 4
1178
1179 =item id
1180
1181 External numeric ID.
1182
1183 =item title
1184
1185 External text title.
1186
1187 =back
1188
1189 Fields used when provisioning an svc_pbx service:
1190
1191 =over 4
1192
1193 =item id
1194
1195 Numeric ID.
1196
1197 =item name
1198
1199 Text name.
1200
1201 =back
1202
1203 Returns a hash reference with a single key, B<error>, empty on success, or an
1204 error message on errors.  The special error '_decline' is returned for
1205 declined transactions.
1206
1207 =item change_pkg
1208
1209 Changes a package for this customer.
1210
1211 Takes a hash reference as parameter with the following keys:
1212
1213 =over 4
1214
1215 =item session_id
1216
1217 Session identifier
1218
1219 =item pkgnum
1220
1221 Existing customer package.
1222
1223 =item pkgpart
1224
1225 New package to order (see L<FS::part_pkg>).
1226
1227 =item quantity
1228
1229 Quantity for this package order (default 1).
1230
1231 =back
1232
1233 Returns a hash reference with the following keys:
1234
1235 =over 4
1236
1237 =item error
1238
1239 Empty on success, or an error message on errors.
1240
1241 =item pkgnum
1242
1243 On success, the new pkgnum
1244
1245 =back
1246
1247
1248 =item renew_info
1249
1250 Provides useful info for early renewals.
1251
1252 Takes a hash reference as parameter with the following keys:
1253
1254 =over 4
1255
1256 =item session_id
1257
1258 Session identifier
1259
1260 =back
1261
1262 Returns a hash reference.  On errors, it contains a single key, B<error>, with
1263 the error message.  Otherwise, contains a single key, B<dates>, pointing to
1264 an array refernce of hash references.  Each hash reference contains the
1265 following keys:
1266
1267 =over 4
1268
1269 =item bill_date
1270
1271 (Future) Bill date.  Indicates a future date for which billing could be run.
1272 Specified as a integer UNIX timestamp.  Pass this value to the B<order_renew>
1273 function.
1274
1275 =item bill_date_pretty
1276
1277 (Future) Bill date as a human-readable string.  (Convenience for display;
1278 subject to change, so best not to parse for the date.)
1279
1280 =item amount
1281
1282 Base amount which will be charged if renewed early as of this date.
1283
1284 =item renew_date
1285
1286 Renewal date; i.e. even-futher future date at which the customer will be paid
1287 through if the early renewal is completed with the given B<bill-date>.
1288 Specified as a integer UNIX timestamp.
1289
1290 =item renew_date_pretty
1291
1292 Renewal date as a human-readable string.  (Convenience for display;
1293 subject to change, so best not to parse for the date.)
1294
1295 =item pkgnum
1296
1297 Package that will be renewed.
1298
1299 =item expire_date
1300
1301 Expiration date of the package that will be renewed.
1302
1303 =item expire_date_pretty
1304
1305 Expiration date of the package that will be renewed, as a human-readable
1306 string.  (Convenience for display; subject to change, so best not to parse for
1307 the date.)
1308
1309 =back
1310
1311 =item order_renew
1312
1313 Renews this customer early; i.e. runs billing for this customer in advance.
1314
1315 Takes a hash reference as parameter with the following keys:
1316
1317 =over 4
1318
1319 =item session_id
1320
1321 Session identifier
1322
1323 =item date
1324
1325 Integer date as returned by the B<renew_info> function, indicating the advance
1326 date for which to run billing.
1327
1328 =back
1329
1330 Returns a hash reference with a single key, B<error>, empty on success, or an
1331 error message on errors.
1332
1333 =item cancel_pkg
1334
1335 Cancels a package for this customer.
1336
1337 Takes a hash reference as parameter with the following keys:
1338
1339 =over 4
1340
1341 =item session_id
1342
1343 Session identifier
1344
1345 =item pkgpart
1346
1347 pkgpart of package to cancel
1348
1349 =back
1350
1351 Returns a hash reference with a single key, B<error>, empty on success, or an
1352 error message on errors.
1353
1354 =item provision_acct
1355
1356 Provisions an account (svc_acct).
1357
1358 Takes a hash reference as parameter with the following keys:
1359
1360 =over 4
1361
1362 =item session_id
1363
1364 Session identifier
1365
1366 =item pkgnum
1367
1368 pkgnum of package into which this service is provisioned
1369
1370 =item svcpart
1371
1372 svcpart or service definition to provision
1373
1374 =item username
1375
1376 =item domsvc
1377
1378 =item _password
1379
1380 =back
1381
1382 =item provision_phone
1383
1384 Provisions a phone number (svc_phone).
1385
1386 Takes a hash reference as parameter with the following keys:
1387
1388 =over 4
1389
1390 =item session_id
1391
1392 Session identifier
1393
1394 =item pkgnum
1395
1396 pkgnum of package into which this service is provisioned
1397
1398 =item svcpart
1399
1400 svcpart or service definition to provision
1401
1402 =item countrycode
1403
1404 =item phonenum
1405
1406 =item address1
1407
1408 =item address2
1409
1410 =item city
1411
1412 =item county
1413
1414 =item state
1415
1416 =item zip
1417
1418 =item country
1419
1420 E911 Address (optional)
1421
1422 =back
1423
1424 =item provision_pbx
1425
1426 Provisions a customer PBX (svc_pbx).
1427
1428 Takes a hash reference as parameter with the following keys:
1429
1430 =over 4
1431
1432 =item session_id
1433
1434 Session identifier
1435
1436 =item pkgnum
1437
1438 pkgnum of package into which this service is provisioned
1439
1440 =item svcpart
1441
1442 svcpart or service definition to provision
1443
1444 =item id
1445
1446 =item title
1447
1448 =item max_extensions
1449
1450 =item max_simultaneous
1451
1452 =item ip_addr
1453
1454 =back
1455
1456 =item provision_external
1457
1458 Provisions an external service (svc_external).
1459
1460 Takes a hash reference as parameter with the following keys:
1461
1462 =over 4
1463
1464 =item session_id
1465
1466 Session identifier
1467
1468 =item pkgnum
1469
1470 pkgnum of package into which this service is provisioned
1471
1472 =item svcpart
1473
1474 svcpart or service definition to provision
1475
1476 =item id
1477
1478 =item title
1479
1480 =back
1481
1482 =back
1483
1484 =head2 "MY ACCOUNT" CONTACT FUNCTIONS
1485
1486 =over 4
1487
1488 =item contact_passwd
1489
1490 Changes the password for the currently-logged in contact.
1491
1492 Takes a hash reference as parameter with the following keys:
1493
1494 =over 4
1495
1496 =item session_id
1497
1498 =item new_password
1499
1500 =back
1501
1502 Returns a hash reference with a single parameter, B<error>, which contains an
1503 error message, or empty on success.
1504
1505 =item list_contacts
1506
1507 Takes a hash reference as parameter with a single key, B<session_id>.
1508
1509 Returns a hash reference with two parameters: B<error>, which contains an error
1510 message, or empty on success, and B<contacts>, a list of contacts.
1511
1512 B<contacts> is an array reference of hash references (i.e. an array of structs,
1513  in XML-RPC).  Each hash reference (struct) has the following keys:
1514
1515 =over 4
1516
1517 =item contactnum
1518
1519 =item class
1520
1521 Contact class name (contact type).
1522
1523 =item first
1524
1525 First name
1526
1527 =item last
1528
1529 Last name
1530
1531 =item title
1532
1533 Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
1534
1535 =item emailaddress
1536
1537 Comma-separated list of email addresses
1538
1539 =item comment
1540
1541 =item selfservice_access
1542
1543 Y when enabled
1544
1545 =back
1546
1547 =item edit_contact
1548
1549 Updates information for the currently-logged in contact, or (optionally) the
1550 specified contact.
1551
1552 Takes a hash reference as parameter with the following keys:
1553
1554 =over 4
1555
1556 =item session_id
1557
1558 =item contactnum
1559
1560 If already logged in as a contact, this is optional.
1561
1562 =item first
1563
1564 =item last
1565
1566 =item emailaddress
1567
1568 =back
1569
1570 Returns a hash reference with a single parameter, B<error>, which contains an
1571 error message, or empty on success.
1572
1573 =item new_contact
1574
1575 Creates a new contact.
1576
1577 Takes a hash reference as parameter with the following keys:
1578
1579 =over 4
1580
1581 =item session_id
1582
1583 =item first
1584
1585 =item last
1586
1587 =item emailaddress
1588
1589 =item classnum
1590
1591 Optional contact classnum (TODO: or name)
1592
1593 =item comment
1594
1595 =item selfservice_access
1596
1597 Y to enable self-service access
1598
1599 =item _password
1600
1601 =back
1602
1603 Returns a hash reference with a single parameter, B<error>, which contains an
1604 error message, or empty on success.
1605
1606 =item delete_contact
1607
1608 Deletes a contact.  (Note: Cannot at this time delete the currently-logged in
1609 contact.)
1610
1611 Takes a hash reference as parameter with the following keys:
1612
1613 =over 4
1614
1615 =item session_id
1616
1617 =item contactnum
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 =back
1625
1626 =head2 "MY ACCOUNT" QUOTATION FUNCTIONS
1627
1628 All of these functions require the user to be logged in, and the 'session_id'
1629 key to be included in the argument hashref.`
1630
1631 =over 4
1632
1633 =item list_quotations HASHREF
1634
1635 Returns a hashref listing this customer's active self-service quotations.
1636 Contents are:
1637
1638 =over 4
1639
1640 =item quotations
1641
1642 an arrayref containing an element for each quotation.
1643
1644 =item quotationnum
1645
1646 the primary key
1647
1648 =item _date
1649
1650 the date it was started
1651
1652 =item num_pkgs
1653
1654 the number of packages
1655
1656 =item total_setup
1657
1658 the sum of setup fees
1659
1660 =item total_recur
1661
1662 the sum of recurring charges
1663
1664 =back
1665
1666 =item quotation_new HASHREF
1667
1668 Creates an empty quotation and returns a hashref containing 'quotationnum',
1669 the primary key of the new quotation.
1670
1671 =item quotation_delete HASHREF
1672
1673 Disables (does not really delete) a quotation. Takes the following arguments:
1674
1675 =over 4
1676
1677 =item session_id
1678
1679 =item quotationnum - the quotation to delete
1680
1681 =back
1682
1683 Returns 'error' => a string, which will be empty on success.
1684
1685 =item quotation_info HASHREF
1686
1687 Returns total and detailed pricing information on a quotation.
1688
1689 Takes the following arguments:
1690
1691 =over 4
1692
1693 =item session_id
1694
1695 =item quotationnum - the quotation to return
1696
1697 =back
1698
1699 Returns a hashref containing:
1700
1701 - total_setup, the total of setup fees (and their taxes)
1702 - total_recur, the total of all recurring charges (and their taxes)
1703 - sections, an arrayref containing an element for each quotation section.
1704   - description, a line of text describing the group of charges
1705   - subtotal, the total of charges in this group (if appropriate)
1706   - detail_items, an arrayref of line items
1707     - pkgnum, the reference number of the package
1708     - description, the package name (or tax name)
1709     - quantity
1710     - amount, the amount charged
1711     If the detail item represents a subtotal, it will instead contain:
1712     - total_item: description of the subtotal
1713     - total_amount: the subtotal amount
1714
1715
1716 =item quotation_print HASHREF
1717
1718 Renders the quotation as HTML or PDF. Takes the following arguments:
1719
1720 =over 4
1721
1722 =item session_id
1723
1724 =item quotationnum - the quotation to return
1725
1726 =item format - 'html' or 'pdf'
1727
1728 =back
1729
1730 Returns a hashref containing 'document', the contents of the file.
1731
1732 =item quotation_add_pkg HASHREF
1733
1734 Adds a package to a quotation. Takes the following arguments:
1735
1736 =over 4
1737
1738 =item session_id
1739
1740 =item pkgpart - the package to add
1741
1742 =item quotationnum - the quotation to add it to
1743
1744 =item quantity - the package quantity (defaults to 1)
1745
1746 =item address1, address2, city, state, zip, country - address fields to set
1747 the service location
1748
1749 =back
1750
1751 Returns 'error' => a string, which will be empty on success.
1752
1753 =item quotation_remove_pkg HASHREF
1754
1755 Removes a package from a quotation. Takes the following arguments:
1756
1757 =over 4
1758
1759 =item session_id
1760
1761 =item pkgnum - the primary key (quotationpkgnum) of the package to remove
1762
1763 =item quotationnum - the quotation to remove it from
1764
1765 =back
1766
1767 Returns 'error' => a string, which will be empty on success.
1768
1769 =item quotation_order HASHREF
1770
1771 Converts the packages in a quotation into real packages. Takes the following
1772 arguments:
1773
1774 Takes the following arguments:
1775
1776 =over 4
1777
1778 =item session_id
1779
1780 =item quotationnum - the quotation to order
1781
1782 =back
1783
1784 =back
1785
1786 =head1 SIGNUP FUNCTIONS
1787
1788 =over 4
1789
1790 =item signup_info HASHREF
1791
1792 Takes a hash reference as parameter with the following keys:
1793
1794 =over 4
1795
1796 =item session_id - Optional agent/reseller interface session
1797
1798 =back
1799
1800 Returns a hash reference containing information that may be useful in
1801 displaying a signup page.  The hash reference contains the following keys:
1802
1803 =over 4
1804
1805 =item cust_main_county
1806
1807 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.
1808
1809 =item part_pkg
1810
1811 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
1812 an agentnum specified explicitly via reseller interface session_id in the
1813 options.
1814
1815 =item agent
1816
1817 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.
1818
1819 =item agentnum2part_pkg
1820
1821 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.
1822
1823 =item svc_acct_pop
1824
1825 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.
1826
1827 =item security_phrase
1828
1829 True if the "security_phrase" feature is enabled
1830
1831 =item payby
1832
1833 Array reference of acceptable payment types for signup
1834
1835 =over 4
1836
1837 =item CARD
1838
1839 credit card - automatic
1840
1841 =item DCRD
1842
1843 credit card - on-demand - version 1.5+ only
1844
1845 =item CHEK
1846
1847 electronic check - automatic
1848
1849 =item DCHK
1850
1851 electronic check - on-demand - version 1.5+ only
1852
1853 =item LECB
1854
1855 Phone bill billing
1856
1857 =item BILL
1858
1859 billing, not recommended for signups
1860
1861 =item COMP
1862
1863 free, definitely not recommended for signups
1864
1865 =item PREPAY
1866
1867 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1868
1869 =back
1870
1871 =item cvv_enabled
1872
1873 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1874
1875 =item msgcat
1876
1877 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".
1878
1879 =item statedefault
1880
1881 Default state
1882
1883 =item countrydefault
1884
1885 Default country
1886
1887 =back
1888
1889 =item new_customer_minimal HASHREF
1890
1891 Creates a new customer.
1892
1893 Current differences from new_customer: An address is not required.  promo_code
1894 and reg_code are not supported.  If invoicing_list and _password is passed, a
1895 contact will be created with self-service access (no pkgpart or username is
1896 necessary).  No initial billing is run (this may change in a future version).
1897
1898 Takes a hash reference as parameter with the following keys:
1899
1900 =over 4
1901
1902 =item first
1903
1904 first name (required)
1905
1906 =item last
1907
1908 last name (required)
1909
1910 =item ss
1911
1912 (not typically collected; mostly used for ACH transactions)
1913
1914 =item company
1915
1916 Company name
1917
1918 =item address1
1919
1920 Address line one
1921
1922 =item address2
1923
1924 Address line two
1925
1926 =item city
1927
1928 City
1929
1930 =item county
1931
1932 County
1933
1934 =item state
1935
1936 State
1937
1938 =item zip
1939
1940 Zip or postal code
1941
1942 =item daytime
1943
1944 Daytime phone number
1945
1946 =item night
1947
1948 Evening phone number
1949
1950 =item fax
1951
1952 Fax number
1953
1954 =item payby
1955
1956 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
1957
1958 =item payinfo
1959
1960 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
1961
1962 =item paycvv
1963
1964 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
1965
1966 =item paydate
1967
1968 Expiration date for CARD/DCRD
1969
1970 =item payname
1971
1972 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
1973
1974 =item invoicing_list
1975
1976 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),
1977
1978 =item referral_custnum
1979
1980 referring customer number
1981
1982 =item agentnum
1983
1984 Agent number
1985
1986 =item pkgpart
1987
1988 pkgpart of initial package
1989
1990 =item username
1991
1992 Username
1993
1994 =item _password
1995
1996 Password
1997
1998 =item sec_phrase
1999
2000 Security phrase
2001
2002 =item popnum
2003
2004 Access number (index, not the literal number)
2005
2006 =item countrycode
2007
2008 Country code (to be provisioned as a service)
2009
2010 =item phonenum
2011
2012 Phone number (to be provisioned as a service)
2013
2014 =item pin
2015
2016 Voicemail PIN
2017
2018 =back
2019
2020 Returns a hash reference with the following keys:
2021
2022 =over 4
2023
2024 =item error
2025
2026 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)
2027
2028 =back
2029
2030 =item new_customer HASHREF
2031
2032 Creates a new customer.  Takes a hash reference as parameter with the
2033 following keys:
2034
2035 =over 4
2036
2037 =item first
2038
2039 first name (required)
2040
2041 =item last
2042
2043 last name (required)
2044
2045 =item ss
2046
2047 (not typically collected; mostly used for ACH transactions)
2048
2049 =item company
2050
2051 Company name
2052
2053 =item address1 (required)
2054
2055 Address line one
2056
2057 =item address2
2058
2059 Address line two
2060
2061 =item city (required)
2062
2063 City
2064
2065 =item county
2066
2067 County
2068
2069 =item state (required)
2070
2071 State
2072
2073 =item zip (required)
2074
2075 Zip or postal code
2076
2077 =item daytime
2078
2079 Daytime phone number
2080
2081 =item night
2082
2083 Evening phone number
2084
2085 =item fax
2086
2087 Fax number
2088
2089 =item payby
2090
2091 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
2092
2093 =item payinfo
2094
2095 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
2096
2097 =item paycvv
2098
2099 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
2100
2101 =item paydate
2102
2103 Expiration date for CARD/DCRD
2104
2105 =item payname
2106
2107 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
2108
2109 =item invoicing_list
2110
2111 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),
2112
2113 =item referral_custnum
2114
2115 referring customer number
2116
2117 =item agentnum
2118
2119 Agent number
2120
2121 =item pkgpart
2122
2123 pkgpart of initial package
2124
2125 =item username
2126
2127 Username
2128
2129 =item _password
2130
2131 Password
2132
2133 =item sec_phrase
2134
2135 Security phrase
2136
2137 =item popnum
2138
2139 Access number (index, not the literal number)
2140
2141 =item countrycode
2142
2143 Country code (to be provisioned as a service)
2144
2145 =item phonenum
2146
2147 Phone number (to be provisioned as a service)
2148
2149 =item pin
2150
2151 Voicemail PIN
2152
2153 =back
2154
2155 Returns a hash reference with the following keys:
2156
2157 =over 4
2158
2159 =item error
2160
2161 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)
2162
2163 =back
2164
2165 =item regionselector HASHREF | LIST
2166
2167 Takes as input a hashref or list of key/value pairs with the following keys:
2168
2169 =over 4
2170
2171 =item selected_county
2172
2173 Currently selected county
2174
2175 =item selected_state
2176
2177 Currently selected state
2178
2179 =item selected_country
2180
2181 Currently selected country
2182
2183 =item prefix
2184
2185 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2186
2187 =item onchange
2188
2189 Specify a javascript subroutine to call on changes
2190
2191 =item default_state
2192
2193 Default state
2194
2195 =item default_country
2196
2197 Default country
2198
2199 =item locales
2200
2201 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>.
2202
2203 =back
2204
2205 Returns a list consisting of three HTML fragments for county selection,
2206 state selection and country selection, respectively.
2207
2208 =cut
2209
2210 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
2211 sub regionselector {
2212   my $param;
2213   if ( ref($_[0]) ) {
2214     $param = shift;
2215   } else {
2216     $param = { @_ };
2217   }
2218   $param->{'selected_country'} ||= $param->{'default_country'};
2219   $param->{'selected_state'} ||= $param->{'default_state'};
2220
2221   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2222
2223   my $countyflag = 0;
2224
2225   my %cust_main_county;
2226
2227 #  unless ( @cust_main_county ) { #cache
2228     #@cust_main_county = qsearch('cust_main_county', {} );
2229     #foreach my $c ( @cust_main_county ) {
2230     foreach my $c ( @{ $param->{'locales'} } ) {
2231       #$countyflag=1 if $c->county;
2232       $countyflag=1 if $c->{county};
2233       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
2234       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
2235       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
2236     }
2237 #  }
2238   $countyflag=1 if $param->{selected_county};
2239
2240   my $script_html = <<END;
2241     <SCRIPT>
2242     function opt(what,value,text) {
2243       var optionName = new Option(text, value, false, false);
2244       var length = what.length;
2245       what.options[length] = optionName;
2246     }
2247     function ${prefix}country_changed(what) {
2248       country = what.options[what.selectedIndex].text;
2249       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
2250           what.form.${prefix}state.options[i] = null;
2251 END
2252       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
2253
2254   foreach my $country ( sort keys %cust_main_county ) {
2255     $script_html .= "\nif ( country == \"$country\" ) {\n";
2256     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2257       my $text = $state || '(n/a)';
2258       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
2259     }
2260     $script_html .= "}\n";
2261   }
2262
2263   $script_html .= <<END;
2264     }
2265     function ${prefix}state_changed(what) {
2266 END
2267
2268   if ( $countyflag ) {
2269     $script_html .= <<END;
2270       state = what.options[what.selectedIndex].text;
2271       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
2272       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
2273           what.form.${prefix}county.options[i] = null;
2274 END
2275
2276     foreach my $country ( sort keys %cust_main_county ) {
2277       $script_html .= "\nif ( country == \"$country\" ) {\n";
2278       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2279         $script_html .= "\nif ( state == \"$state\" ) {\n";
2280           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
2281           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
2282             my $text = $county || '(n/a)';
2283             $script_html .=
2284               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
2285           }
2286         $script_html .= "}\n";
2287       }
2288       $script_html .= "}\n";
2289     }
2290   }
2291
2292   $script_html .= <<END;
2293     }
2294     </SCRIPT>
2295 END
2296
2297   my $county_html = $script_html;
2298   if ( $countyflag ) {
2299     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
2300     foreach my $county (
2301       sort keys %{ $cust_main_county{$param->{'selected_country'}}{$param->{'selected_state'}} }
2302     ) {
2303       my $text = $county || '(n/a)';
2304       $county_html .= qq!<OPTION VALUE="$county"!.
2305                       ($county eq $param->{'selected_county'} ?
2306                         ' SELECTED>' :
2307                         '>'
2308                       ).
2309                       $text.
2310                       '</OPTION>';
2311     }
2312     $county_html .= '</SELECT>';
2313   } else {
2314     $county_html .=
2315       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
2316   }
2317
2318   my $state_html = qq!<SELECT NAME="${prefix}state" !.
2319                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
2320   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
2321     my $text = $state || '(n/a)';
2322     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
2323     $state_html .= "\n<OPTION $selected VALUE=\"$state\">$text</OPTION>"
2324   }
2325   $state_html .= '</SELECT>';
2326
2327   my $country_html = '';
2328   if ( scalar( keys %cust_main_county ) > 1 )  {
2329
2330     $country_html = qq(<SELECT NAME="${prefix}country" ).
2331                     qq(onChange="${prefix}country_changed(this); ).
2332                                  $param->{'onchange'}.
2333                                '"'.
2334                       '>';
2335     my $countrydefault = $param->{default_country} || 'US';
2336     foreach my $country (
2337       sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
2338         keys %cust_main_county
2339     ) {
2340       my $selected = $country eq $param->{'selected_country'}
2341                        ? ' SELECTED'
2342                        : '';
2343       $country_html .= "\n<OPTION $selected>$country</OPTION>"
2344     }
2345     $country_html .= '</SELECT>';
2346   } else {
2347
2348     $country_html = qq(<INPUT TYPE="hidden" NAME="${prefix}country" ).
2349                             ' VALUE="'. (keys %cust_main_county )[0]. '">';
2350
2351   }
2352
2353   ($county_html, $state_html, $country_html);
2354
2355 }
2356
2357 sub regionselector_hashref {
2358   my ($county_html, $state_html, $country_html) = regionselector(@_);
2359   {
2360     'county_html'  => $county_html,
2361     'state_html'   => $state_html,
2362     'country_html' => $country_html,
2363   };
2364 }
2365
2366 =item location_form HASHREF | LIST
2367
2368 Takes as input a hashref or list of key/value pairs with the following keys:
2369
2370 =over 4
2371
2372 =item session_id
2373
2374 Current customer session_id
2375
2376 =item no_asterisks
2377
2378 Omit red asterisks from required fields.
2379
2380 =item address1_label
2381
2382 Label for first address line.
2383
2384 =back
2385
2386 Returns an HTML fragment for a location form (address, city, state, zip,
2387 country)
2388
2389 =cut
2390
2391 sub location_form {
2392   my $param;
2393   if ( ref($_[0]) ) {
2394     $param = shift;
2395   } else {
2396     $param = { @_ };
2397   }
2398
2399   my $session_id = delete $param->{'session_id'};
2400
2401   my $rv = mason_comp( 'session_id' => $session_id,
2402                        'comp'       => '/elements/location.html',
2403                        'args'       => [ %$param ],
2404                      );
2405
2406   #hmm.
2407   $rv->{'error'} || $rv->{'output'};
2408
2409 }
2410
2411
2412 #=item expselect HASHREF | LIST
2413 #
2414 #Takes as input a hashref or list of key/value pairs with the following keys:
2415 #
2416 #=over 4
2417 #
2418 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2419 #
2420 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
2421 #
2422 #=back
2423
2424 =item expselect PREFIX [ DATE ]
2425
2426 Takes as input a unique prefix string and the current expiration date, in
2427 yyyy-mm-dd or m-d-yyyy format
2428
2429 Returns an HTML fragments for expiration date selection.
2430
2431 =cut
2432
2433 sub expselect {
2434   #my $param;
2435   #if ( ref($_[0]) ) {
2436   #  $param = shift;
2437   #} else {
2438   #  $param = { @_ };
2439   #my $prefix = $param->{'prefix'};
2440   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2441   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
2442   my $prefix = shift;
2443   my $date = scalar(@_) ? shift : '';
2444
2445   my( $m, $y ) = ( 0, 0 );
2446   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
2447     ( $m, $y ) = ( $2, $1 );
2448   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
2449     ( $m, $y ) = ( $1, $3 );
2450   }
2451   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
2452   for ( 1 .. 12 ) {
2453     $return .= qq!<OPTION VALUE="$_"!;
2454     $return .= " SELECTED" if $_ == $m;
2455     $return .= ">$_";
2456   }
2457   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
2458   my @t = localtime;
2459   my $thisYear = $t[5] + 1900;
2460   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
2461     $return .= qq!<OPTION VALUE="$_"!;
2462     $return .= " SELECTED" if $_ == $y;
2463     $return .= ">$_";
2464   }
2465   $return .= "</SELECT>";
2466
2467   $return;
2468 }
2469
2470 =item popselector HASHREF | LIST
2471
2472 Takes as input a hashref or list of key/value pairs with the following keys:
2473
2474 =over 4
2475
2476 =item popnum
2477
2478 Access number number
2479
2480 =item pops
2481
2482 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>.
2483
2484 =back
2485
2486 Returns an HTML fragment for access number selection.
2487
2488 =cut
2489
2490 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
2491 sub popselector {
2492   my $param;
2493   if ( ref($_[0]) ) {
2494     $param = shift;
2495   } else {
2496     $param = { @_ };
2497   }
2498   my $popnum = $param->{'popnum'};
2499   my $pops = $param->{'pops'};
2500
2501   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
2502   return $pops->[0]{city}. ', '. $pops->[0]{state}.
2503          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
2504          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
2505     if scalar(@$pops) == 1;
2506
2507   my %pop = ();
2508   my %popnum2pop = ();
2509   foreach (@$pops) {
2510     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
2511     $popnum2pop{$_->{popnum}} = $_;
2512   }
2513
2514   my $text = <<END;
2515     <SCRIPT>
2516     function opt(what,href,text) {
2517       var optionName = new Option(text, href, false, false)
2518       var length = what.length;
2519       what.options[length] = optionName;
2520     }
2521 END
2522
2523   my $init_popstate = $param->{'init_popstate'};
2524   if ( $init_popstate ) {
2525     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
2526              $init_popstate. '">';
2527   } else {
2528     $text .= <<END;
2529       function acstate_changed(what) {
2530         state = what.options[what.selectedIndex].text;
2531         what.form.popac.options.length = 0
2532         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
2533 END
2534   }
2535
2536   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
2537   foreach my $state ( sort { $a cmp $b } @states ) {
2538     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
2539
2540     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
2541       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
2542       if ($ac eq $param->{'popac'}) {
2543         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
2544       }
2545     }
2546     $text .= "}\n" unless $init_popstate;
2547   }
2548   $text .= "popac_changed(what.form.popac)}\n";
2549
2550   $text .= <<END;
2551   function popac_changed(what) {
2552     ac = what.options[what.selectedIndex].text;
2553     what.form.popnum.options.length = 0;
2554     what.form.popnum.options[0] = new Option("City", "-1", false, true);
2555
2556 END
2557
2558   foreach my $state ( @states ) {
2559     foreach my $popac ( keys %{ $pop{$state} } ) {
2560       $text .= "\nif ( ac == \"$popac\" ) {\n";
2561
2562       foreach my $pop ( @{$pop{$state}->{$popac}}) {
2563         my $o_popnum = $pop->{popnum};
2564         my $poptext =  $pop->{city}. ', '. $pop->{state}.
2565                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2566
2567         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
2568         if ($popnum == $o_popnum) {
2569           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
2570         }
2571       }
2572       $text .= "}\n";
2573     }
2574   }
2575
2576
2577   $text .= "}\n</SCRIPT>\n";
2578
2579   $param->{'acstate'} = '' unless defined($param->{'acstate'});
2580
2581   $text .=
2582     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
2583     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
2584   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
2585            ">$_" foreach sort { $a cmp $b } @states;
2586   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
2587
2588   $text .=
2589     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
2590     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
2591
2592   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
2593
2594
2595   #comment this block to disable initial list polulation
2596   my @initial_select = ();
2597   if ( scalar( @$pops ) > 100 ) {
2598     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
2599   } else {
2600     @initial_select = @$pops;
2601   }
2602   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
2603     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
2604              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
2605              $pop->{city}. ', '. $pop->{state}.
2606                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2607   }
2608
2609   $text .= qq!</SELECT></TD></TR></TABLE>!;
2610
2611   $text;
2612
2613 }
2614
2615 =item domainselector HASHREF | LIST
2616
2617 Takes as input a hashref or list of key/value pairs with the following keys:
2618
2619 =over 4
2620
2621 =item pkgnum
2622
2623 Package number
2624
2625 =item domsvc
2626
2627 Service number of the selected item.
2628
2629 =back
2630
2631 Returns an HTML fragment for domain selection.
2632
2633 =cut
2634
2635 sub domainselector {
2636   my $param;
2637   if ( ref($_[0]) ) {
2638     $param = shift;
2639   } else {
2640     $param = { @_ };
2641   }
2642   my $domsvc= $param->{'domsvc'};
2643   my $rv =
2644       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
2645   my $domains = $rv->{'domains'};
2646   $domsvc = $rv->{'domsvc'} unless $domsvc;
2647
2648   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
2649     unless scalar(keys %$domains);
2650
2651   if (scalar(keys %$domains) == 1) {
2652     my $key;
2653     foreach(keys %$domains) {
2654       $key = $_;
2655     }
2656     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
2657            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
2658   }
2659
2660   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em">!;
2661
2662   $text .= '<OPTION>(Choose Domain)' unless $domsvc;
2663
2664   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
2665     $text .= qq!<OPTION VALUE="!. $domain. '"'.
2666              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
2667              $domains->{$domain};
2668   }
2669
2670   $text .= qq!</SELECT></TD></TR>!;
2671
2672   $text;
2673
2674 }
2675
2676 =item didselector HASHREF | LIST
2677
2678 Takes as input a hashref or list of key/value pairs with the following keys:
2679
2680 =over 4
2681
2682 =item field
2683
2684 Field name for the returned HTML fragment.
2685
2686 =item svcpart
2687
2688 Service definition (see L<FS::part_svc>)
2689
2690 =back
2691
2692 Returns an HTML fragment for DID selection.
2693
2694 =cut
2695
2696 sub didselector {
2697   my $param;
2698   if ( ref($_[0]) ) {
2699     $param = shift;
2700   } else {
2701     $param = { @_ };
2702   }
2703
2704   my $rv = mason_comp( 'comp'=>'/elements/select-did.html',
2705                        'args'=>[ %$param ],
2706                      );
2707
2708   #hmm.
2709   $rv->{'error'} || $rv->{'output'};
2710
2711 }
2712
2713 =back
2714
2715 =head1 RESELLER FUNCTIONS
2716
2717 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
2718 with their active session, and the B<customer_info> and B<order_pkg> functions
2719 with their active session and an additional I<custnum> parameter.
2720
2721 For the most part, development of the reseller web interface has been
2722 superceded by agent-virtualized access to the backend.
2723
2724 =over 4
2725
2726 =item agent_login
2727
2728 Agent login
2729
2730 =item agent_info
2731
2732 Agent info
2733
2734 =item agent_list_customers
2735
2736 List agent's customers.
2737
2738 =back
2739
2740 =head1 BUGS
2741
2742 =head1 SEE ALSO
2743
2744 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
2745
2746 =cut
2747
2748 1;
2749